FE-1158: Add boolean predicates to experiment metrics

libs/@hashintel/petrinaut-core/src/hir.ts

@@ -20,8 +20,10 @@ export {
 } from "./hir/analyze";
 export {
   compileHirArtifacts,
+  type HirCompileOptions,
   type HirCompileFailure,
   type HirCompileResult,
+  type HirMetricReturnType,
 } from "./hir/compile";
 export {
   hirDistributionRuntime,

libs/@hashintel/petrinaut-core/src/hir/BUFFER_ABI.md

@@ -101,12 +101,18 @@ The field order matches `TokenSlotLayout.realFieldF64Offsets`.
 
 ## Metrics
 
-Metrics read a frame's raw token region and dense place metadata:
+Metric-shaped frame readers — numeric metrics and boolean experiment
+predicates — read a frame's raw token region and dense place metadata:
 
 ```ts
-(f64, u64, u8, placeCounts, placeOffsets) => number;
+(f64, u64, u8, placeCounts, placeOffsets) => number | boolean;
 ```
 
+Numeric metrics must return a finite number. Predicates are compiled with a
+boolean return type (`HirMetricContext.returnType` /
+`HirCompileOptions.metricReturnTypes`) and must return a boolean; the runtime
+evaluators enforce the respective return type per call.
+
 `HirMetricArtifact.placeNames` records places in first-reference order. At
 instantiation, `__places[ordinal]` maps those names to frame place indexes.
 

libs/@hashintel/petrinaut-core/src/hir/compile.ts

@@ -57,6 +57,17 @@ export type HirCompileResult = {
   failures: HirCompileFailure[];
 };
 
+export type HirMetricReturnType = "number" | "boolean";
+
+export type HirCompileOptions = {
+  /**
+   * Optional per-metric return-type override. Regular model metrics default to
+   * numeric; experiment predicates use the same metric-shaped frame surface but
+   * compile as boolean-returning artifacts.
+   */
+  metricReturnTypes?: Readonly<Record<string, HirMetricReturnType>>;
+};
+
 function notCompilableDiagnostic(fn: HirFunction): HirDiagnostic {
   return {
     code: "hir:not-compilable",
@@ -102,6 +113,7 @@ function lowerAndCheck(
 export function compileHirArtifacts(
   sdcpn: SDCPN,
   extensions: PetrinautExtensionSettings = DEFAULT_PETRINAUT_EXTENSIONS,
+  options: HirCompileOptions = {},
 ): HirCompileResult {
   const sanitized = sanitizeSDCPNForExtensions(sdcpn, extensions);
   const artifacts: HirArtifacts = {
@@ -248,7 +260,10 @@ export function compileHirArtifacts(
       // error, but they must not block the rest of the net from compiling.
       continue;
     }
-    const item = lowerAndCheck(metric.code, "metric", metricContext);
+    const item = lowerAndCheck(metric.code, "metric", {
+      ...metricContext,
+      returnType: options.metricReturnTypes?.[metric.id] ?? "number",
+    });
     if (!item.ok) {
       failures.push({
         itemId: metric.id,

libs/@hashintel/petrinaut-core/src/hir/emit-buffer-js.ts

@@ -7,7 +7,7 @@
  *
  *   lambda: (f64, u64, u8, placeBases, indices) => number | boolean
  *   kernel: (f64, u64, u8, placeBases, indices, outF64, outU64, outU8, sink) => void
- *   metric: (f64, u64, u8, placeCounts, placeOffsets) => number
+ *   metric-shaped frame reader: (f64, u64, u8, placeCounts, placeOffsets) => number | boolean
  *
  * The full ABI is documented in `BUFFER_ABI.md`.
  *
@@ -928,9 +928,9 @@ export function emitBufferKernelJs(
 }
 
 /**
- * Emits a buffer-ABI metric program (token format v2):
+ * Emits a buffer-ABI metric-shaped frame-reader program (token format v2):
  *
- *   (f64, u64, u8, placeCounts, placeOffsets) => number
+ *   (f64, u64, u8, placeCounts, placeOffsets) => number | boolean
  *
  * - `f64`/`u64`/`u8` — shared views over the frame's token byte region.
  * - `placeCounts`/`placeOffsets` — the frame's dense per-place token counts

libs/@hashintel/petrinaut-core/src/hir/instantiate.ts

@@ -57,16 +57,17 @@ export type HirCompiledBufferLambda = (
 /**
  * Buffer-ABI metric: reads a frame's packed token region through shared
  * views plus its dense per-place `placeCounts`/`placeOffsets` arrays and
- * returns one number. The place-ordinal→frame-place-index table and string
- * pool are pre-bound at instantiation.
+ * returns one scalar. Numeric metrics and boolean predicates share this ABI.
+ * The place-ordinal→frame-place-index table and string pool are pre-bound at
+ * instantiation.
  */
 export type HirCompiledMetric = (
   f64: Float64Array,
   u64: BigUint64Array,
   u8: Uint8Array,
   placeCounts: Uint32Array,
   placeOffsets: Uint32Array,
-) => number;
+) => number | boolean;
 
 /** Buffer-ABI kernel: writes output attributes into per-transition staging
  * (place-major, baked offsets); RNG-consuming slots defer through the sink. */
@@ -203,11 +204,12 @@ export function instantiateHirBufferKernel(
 }
 
 /**
- * Instantiates a compiled metric program. `placeIndices[ordinal]` maps each
+ * Instantiates a compiled metric-shaped frame-reader program.
+ * `placeIndices[ordinal]` maps each
  * of the artifact's `placeNames` to the frame's place index (resolve once
- * per experiment/simulation, not per frame). Metrics have no parameters
- * object and never intern strings; `__params`/`__dist` are bound for ABI
- * parity with the other programs but unused.
+ * per experiment/simulation, not per frame). Metrics and predicates have no
+ * parameters object and never intern strings; `__params`/`__dist` are bound
+ * for ABI parity with the other programs but unused.
  */
 export function instantiateHirMetric(
   source: string,

libs/@hashintel/petrinaut-core/src/hir/lint.test.ts

@@ -331,6 +331,14 @@ return all.reduce((sum, t) => sum + t.x, 0) / all.length;`,
         "error",
       ]);
 
+      // Predicate sessions reuse the metric state surface but return booleans.
+      expect(
+        codes(`return true;`, { ...metricContext, returnType: "boolean" }),
+      ).toEqual([]);
+      expect(
+        codes(`return 1;`, { ...metricContext, returnType: "boolean" }),
+      ).toContainEqual(["hir:metric-return", "error"]);
+
       // Unknown place.
       expect(
         codes(`return state.places.Missing.count;`, metricContext),

libs/@hashintel/petrinaut-core/src/hir/surface-context.ts

@@ -126,6 +126,13 @@ export type HirMetricContext = {
   surface: "metric";
   /** Metrics have no parameters object — always empty. */
   parameters: HirParameterInfo[];
+  /**
+   * The scalar result expected from the metric-shaped frame reader surface.
+   *
+   * Experiment predicates reuse the same `state` object and buffer emission as
+   * metrics, but they return a boolean instead of a numeric sample.
+   */
+  returnType?: "number" | "boolean";
   /** ALL places of the root net, keyed by display name (last name wins for
    * duplicates, matching the runtime object-key overwrite). */
   places: HirMetricPlaceInfo[];

libs/@hashintel/petrinaut-core/src/hir/typecheck.ts

@@ -747,6 +747,17 @@ class Typechecker {
         return;
       }
       case "metric": {
+        if (context.returnType === "boolean") {
+          if (!isBoolish(returnType)) {
+            this.report(
+              bodySpan,
+              "hir:metric-return",
+              `Predicates must return a boolean, got ${formatHirType(returnType)}.`,
+            );
+          }
+          return;
+        }
+
         if (!isNumeric(returnType)) {
           this.report(
             bodySpan,

libs/@hashintel/petrinaut-core/src/index.ts

@@ -181,8 +181,10 @@ export type {
   MonteCarloExperiment,
   MonteCarloExperimentEvent,
   MonteCarloExperimentMetrics,
+  MonteCarloExperimentPredicates,
   MonteCarloExperimentState,
   MonteCarloExpressionMetricSpec,
+  MonteCarloNumericMetricSpec,
   MonteCarloFrameMetric,
   MonteCarloFrameMetricContext,
   MonteCarloMetricDistributionBinning,
@@ -191,10 +193,12 @@ export type {
   MonteCarloMetricNumericAccumulatorState,
   MonteCarloMetricSpec,
   MonteCarloMetricSpecBase,
+  MonteCarloMetricType,
   MonteCarloMetricRunOutput,
   MonteCarloMetricRunStatus,
   MonteCarloMetricValueAccumulator,
   MonteCarloPlaceTokenCountMeanMetricSpec,
+  MonteCarloPredicateSpec,
   MonteCarloRunFrameMetricView,
   MonteCarloRunFrameMetricVisitor,
   MonteCarloRunConfig,
@@ -214,6 +218,11 @@ export type {
   MonteCarloUserDefinedMetricSampleRuns,
   MonteCarloUserDefinedScalarMetricFrame,
   MonteCarloUserDefinedMetricTimeAggregation,
+  MonteCarloUserDefinedPredicate,
+  MonteCarloUserDefinedPredicateConfig,
+  MonteCarloUserDefinedPredicateMeasureInput,
+  MonteCarloUserDefinedPredicateRunResult,
+  MonteCarloUserDefinedPredicateSnapshot,
   MonteCarloTransitionFiringCountMetricSpec,
   MonteCarloWorkerProgress,
 } from "./simulation";
@@ -248,6 +257,7 @@ export type {
 // LSP worker, runtime instantiation in ./hir-runtime) ---
 export type {
   HirArtifacts,
+  HirCompileOptions,
   HirCompileFailure,
   HirCompileResult,
   HirDiagnostic,

libs/@hashintel/petrinaut-core/src/lsp/language-client.ts

@@ -8,7 +8,7 @@ import {
 
 import type { PetrinautExtensionSettings } from "../extensions";
 // Type-only: must not pull the compiler (`typescript`) into client bundles.
-import type { HirCompileResult } from "../hir";
+import type { HirCompileOptions, HirCompileResult } from "../hir";
 import type { ReadableStore } from "../store";
 import type { SDCPN } from "../types/sdcpn";
 import type {
@@ -93,6 +93,7 @@ export interface LanguageClient {
     this: void,
     sdcpn: SDCPN,
     extensions?: PetrinautExtensionSettings,
+    options?: HirCompileOptions,
   ): Promise<HirCompileResult>;
 
   /**
@@ -314,10 +315,11 @@ export function createLanguageClient(
         position,
       });
     },
-    requestHirArtifacts(sdcpn, extensions) {
+    requestHirArtifacts(sdcpn, extensions, options) {
       return sendRequest<HirCompileResult>("sdcpn/compileHirArtifacts", {
         sdcpn,
         extensions,
+        options,
       });
     },
 

libs/@hashintel/petrinaut-core/src/lsp/lib/create-sdcpn-language-service.test.ts

@@ -409,4 +409,26 @@ describe("SDCPNLanguageServer completions", () => {
       expect(names).toContain("gravity");
     });
   });
+
+  describe("metric session files", () => {
+    it("wraps boolean-return sessions as predicates", () => {
+      const sdcpn = createSDCPN({
+        places: [{ id: "place1", name: "Done", colorId: null }],
+      });
+      const server = new SDCPNLanguageServer();
+      server.syncMetricFiles(sdcpn, {
+        sessionId: "predicate-session",
+        code: "return state.places.Done.count > 0;",
+        returnType: "boolean",
+      });
+
+      const filePath = getItemFilePath("metric-code", {
+        sessionId: "predicate-session",
+      });
+
+      expect(server.getFileContent(filePath)).toContain(
+        "function __metric(state: MetricState): boolean",
+      );
+    });
+  });
 });

libs/@hashintel/petrinaut-core/src/lsp/lib/generate-virtual-files.ts

@@ -583,16 +583,18 @@ export function generateScenarioSessionFiles(
  */
 export type MetricSessionData = {
   sessionId: string;
-  /** Metric function body (must `return` a finite number). */
+  /** Metric-shaped function body. Metrics return numbers; predicates return booleans. */
   code: string;
+  returnType?: "number" | "boolean";
 };
 
 /**
  * Generates virtual files for a metric editing session.
  *
  * The user code is a function body whose `state` parameter exposes
  * `state.places.<PlaceName>` with `count` and (for colored places) `tokens`.
- * The expression is wrapped so the body is type-checked as `(state) => number`.
+ * The expression is wrapped so the body is type-checked as `(state) => number`
+ * for metrics and `(state) => boolean` for predicates.
  */
 export function generateMetricSessionFiles(
   sdcpn: SDCPN,
@@ -659,7 +661,7 @@ export function generateMetricSessionFiles(
   files.set(codePath, {
     prefix: [
       `import type { MetricState } from "${defsPath}";`,
-      `function __metric(state: MetricState): number {`,
+      `function __metric(state: MetricState): ${session.returnType ?? "number"} {`,
       "",
     ].join("\n"),
     content: session.code,

libs/@hashintel/petrinaut-core/src/lsp/worker/language-server.worker.ts

@@ -147,7 +147,10 @@ function publishAllDiagnostics(
       );
       if (!hasTsError) {
         allDiags.push(
-          ...getHirDiagnosticsForItem(userContent, metricHirContext),
+          ...getHirDiagnosticsForItem(userContent, {
+            ...metricHirContext,
+            returnType: session.returnType ?? "number",
+          }),
         );
       }
       params.push({
@@ -197,6 +200,7 @@ function toMetricSessionData(params: MetricSessionParams): MetricSessionData {
   return {
     sessionId: params.sessionId,
     code: params.code,
+    returnType: params.returnType,
   };
 }
 
@@ -384,7 +388,11 @@ workerRuntime.onMessage((data) => {
         const { id } = data;
         respond(
           id,
-          compileHirArtifacts(data.params.sdcpn, data.params.extensions),
+          compileHirArtifacts(
+            data.params.sdcpn,
+            data.params.extensions,
+            data.params.options,
+          ),
         );
         break;
       }

libs/@hashintel/petrinaut-core/src/lsp/worker/protocol.ts

@@ -13,6 +13,7 @@
  * upstream package directly.
  */
 import type { PetrinautExtensionSettings } from "../../extensions";
+import type { HirCompileOptions } from "../../hir";
 import type { SDCPN, ScenarioParameter } from "../../types/sdcpn";
 import type {
   Diagnostic,
@@ -51,8 +52,9 @@ export type ScenarioSessionParams = {
  */
 export type MetricSessionParams = {
   sessionId: string;
-  /** Metric function body (must `return` a finite number). */
+  /** Metric-shaped function body. Metrics return numbers; predicates return booleans. */
   code: string;
+  returnType?: "number" | "boolean";
 };
 
 /** Position in a text document (LSP standard: line/character based). */
@@ -143,6 +145,7 @@ type ClientRequest =
       params: {
         sdcpn: SDCPN;
         extensions?: PetrinautExtensionSettings;
+        options?: HirCompileOptions;
       };
     };