FE-769: String token dimension type

Plain JS strings in user code, stored via per-run interning: frame
buffers hold u64 references into an append-only pool owned by the
simulation; interactive runs ship newStrings deltas with frame
payloads. Editing a type's schema now migrates stored initial state
(scenario rows and session marking) with value coercion.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: kube

.changeset/fe-769-string-token-dimension-type.md

@@ -0,0 +1,6 @@
+---
+"@hashintel/petrinaut": patch
+"@hashintel/petrinaut-core": patch
+---
+
+Add the `string` token attribute type, stored via per-run interning. Editing a type's schema now migrates stored initial state (values convert, falling back to the new type's default).

libs/@hashintel/petrinaut-core/docs/architecture/engine.html

@@ -708,6 +708,17 @@ <h2>Token memory layout — packed structs</h2>
             optional — omitted values auto-generate from the seeded RNG.
           </td>
         </tr>
+        <tr>
+          <td><code>string</code> (FE-769)</td>
+          <td><code>u64</code> pool reference — 8 B</td>
+          <td>
+            The frame stores an ID into an append-only per-run string intern
+            pool (<code>engine/string-pool.ts</code>); the pool lives on
+            <code>SimulationInstance</code>, not on the frame, so frames stay
+            fixed-stride and byte-copyable. Equal strings share one ID; id 0 is
+            the pre-seeded <code>""</code>, so zeroed buffers decode cleanly.
+          </td>
+        </tr>
       </tbody>
     </table>
     <ul>
@@ -726,7 +737,11 @@ <h2>Token memory layout — packed structs</h2>
         only code that indexes token bytes; all whole-token moves are byte-range
         copies (<code>Uint8Array.set</code>). The raw
         <code>getPlaceTokenValues</code> reader was removed from the public API
-        — raw f64 access is meaningless under mixed widths.
+        — raw f64 access is meaningless under mixed widths. Because the string
+        pool never crosses the worker boundary with the frames, each frame
+        payload ships an append-only <code>newStrings</code> delta that the
+        main-thread frame store accumulates and hands to the frame reader for
+        decoding.
       </li>
     </ul>
 

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

@@ -32,6 +32,7 @@ import {
   stripDisabledExtensionData,
   type PetrinautExtensionSettings,
 } from "./extensions";
+import { migrateScenarioRowsForTypeEdit } from "./schema-migration";
 
 import type {
   ArcEndpoint,
@@ -768,6 +769,10 @@ export function createPetrinautActions(
           if (type.id === parsed.typeId) {
             type.elements.push(parsed.element);
             colorSchema.parse(type);
+            migrateScenarioRowsForTypeEdit(sdcpn, parsed.typeId, {
+              kind: "add",
+              element: parsed.element,
+            });
             break;
           }
         }
@@ -782,10 +787,21 @@ export function createPetrinautActions(
         const net = resolveTargetNet(sdcpn, parsed.targetSubnetId);
         for (const type of net.types) {
           if (type.id === parsed.typeId) {
-            for (const element of type.elements) {
+            for (const [index, element] of type.elements.entries()) {
               if (element.elementId === parsed.elementId) {
+                const previousElementType = element.type;
                 Object.assign(element, parsed.update);
                 colorSchema.parse(type);
+                if (
+                  parsed.update.type !== undefined &&
+                  parsed.update.type !== previousElementType
+                ) {
+                  migrateScenarioRowsForTypeEdit(sdcpn, parsed.typeId, {
+                    kind: "changeType",
+                    index,
+                    element,
+                  });
+                }
                 break;
               }
             }
@@ -807,6 +823,10 @@ export function createPetrinautActions(
               if (element.elementId === parsed.elementId) {
                 type.elements.splice(index, 1);
                 colorSchema.parse(type);
+                migrateScenarioRowsForTypeEdit(sdcpn, parsed.typeId, {
+                  kind: "remove",
+                  index,
+                });
                 break;
               }
             }
@@ -834,6 +854,18 @@ export function createPetrinautActions(
             if (element) {
               type.elements.splice(parsed.toIndex, 0, element);
               colorSchema.parse(type);
+              // Use the actual landing index (splice clamps out-of-range
+              // destinations to the end of the array).
+              const toIndex = type.elements.findIndex(
+                (candidate) => candidate.elementId === parsed.elementId,
+              );
+              if (toIndex !== fromIndex) {
+                migrateScenarioRowsForTypeEdit(sdcpn, parsed.typeId, {
+                  kind: "move",
+                  fromIndex,
+                  toIndex,
+                });
+              }
             }
             break;
           }

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

@@ -269,12 +269,12 @@ Validate every code-writing change. After any tool call that writes code — lam
 Place names are part of the code surface: lambdas/kernels read \`input.PlaceName\`, metrics read \`state.places.PlaceName.count\`, and scenario code-mode initial state keys are place names. Renaming a place via \`updatePlace\` requires updating every dependent lambda, kernel, dynamics, metric, visualizer, and scenario in the same batch — otherwise you will silently break references.
 
 Code-surface cheatsheet (exact shapes expected by the runtime):
-- Transition lambda (\`transition.lambdaCode\`): \`export default Lambda((input, parameters) => …)\`. Available when stochasticity is enabled OR when colours are enabled and the transition has at least one standard or read input arc from a coloured place. \`input.PlaceName\` is a tuple sized to the input arc weight for coloured standard and read input arcs; token attributes are typed by the colour element: real/integer → number, boolean → boolean, uuid → bigint. Read arcs expose tokens in \`input\` but do not consume them when the transition fires. Inhibitor arcs and uncoloured input places are NOT in \`input\`. Predicate → boolean; stochastic → non-negative rate in firings per simulation second (0 disables, Infinity always fires). Must be deterministic. If unavailable or empty, the runtime uses true for predicate-style transitions and Infinity for stochastic-style transitions.
-- Transition kernel (\`transition.transitionKernelCode\`): \`export default TransitionKernel((input, parameters) => …)\`. Available only for transitions with coloured output places. Return \`{ OutputPlaceName: [token, …] }\` sized to the output arc weight. Include only coloured output places; uncoloured output places are auto-populated. Output values must match element types: real/integer use numbers, boolean uses booleans. uuid attributes are OPTIONAL in output tokens: omit them to auto-generate a fresh UUID deterministically from the seeded simulation RNG, use \`Uuid.generate()\` for an explicit fresh UUID, \`Uuid.from(value)\` to derive one from any value, or forward an input token's uuid bigint unchanged; plain non-UUID values (numbers, arbitrary strings) are converted deterministically via UUIDv5. When stochasticity is enabled, real attributes may use \`Distribution.Gaussian(mean, sd)\` / \`Distribution.Uniform(min, max)\` / \`Distribution.Lognormal(mu, sigma)\` (never integer/boolean/uuid attributes), and chained \`.map(fn)\` on the same distribution shares one draw. When stochasticity is disabled, kernel outputs must use plain values only. Leave empty when no coloured outputs exist.
-- Differential equation (\`differentialEquation.code\`): \`export default Dynamics((tokens, parameters) => …)\`. \`tokens\` is THIS place's tokens only. Return an array of the same length whose entries provide derivatives for real-valued elements only (i.e. dx/dt, not the new value); integer, boolean, and uuid elements are discrete and remain unchanged by dynamics. The equation's \`colorId\` MUST match every referencing place's \`colorId\`.
+- Transition lambda (\`transition.lambdaCode\`): \`export default Lambda((input, parameters) => …)\`. Available when stochasticity is enabled OR when colours are enabled and the transition has at least one standard or read input arc from a coloured place. \`input.PlaceName\` is a tuple sized to the input arc weight for coloured standard and read input arcs; token attributes are typed by the colour element: real/integer → number, boolean → boolean, uuid → bigint, string → string (plain JS strings everywhere, compared by value). Read arcs expose tokens in \`input\` but do not consume them when the transition fires. Inhibitor arcs and uncoloured input places are NOT in \`input\`. Predicate → boolean; stochastic → non-negative rate in firings per simulation second (0 disables, Infinity always fires). Must be deterministic. If unavailable or empty, the runtime uses true for predicate-style transitions and Infinity for stochastic-style transitions.
+- Transition kernel (\`transition.transitionKernelCode\`): \`export default TransitionKernel((input, parameters) => …)\`. Available only for transitions with coloured output places. Return \`{ OutputPlaceName: [token, …] }\` sized to the output arc weight. Include only coloured output places; uncoloured output places are auto-populated. Output values must match element types: real/integer use numbers, boolean uses booleans, string uses plain strings (REQUIRED in the token type; a missing/undefined value becomes the empty string \`""\`, and non-string values are stringified via \`String(value)\`). uuid attributes are OPTIONAL in output tokens: omit them to auto-generate a fresh UUID deterministically from the seeded simulation RNG, use \`Uuid.generate()\` for an explicit fresh UUID, \`Uuid.from(value)\` to derive one from any value, or forward an input token's uuid bigint unchanged; plain non-UUID values (numbers, arbitrary strings) are converted deterministically via UUIDv5. When stochasticity is enabled, real attributes may use \`Distribution.Gaussian(mean, sd)\` / \`Distribution.Uniform(min, max)\` / \`Distribution.Lognormal(mu, sigma)\` (never integer/boolean/uuid/string attributes), and chained \`.map(fn)\` on the same distribution shares one draw. When stochasticity is disabled, kernel outputs must use plain values only. Leave empty when no coloured outputs exist.
+- Differential equation (\`differentialEquation.code\`): \`export default Dynamics((tokens, parameters) => …)\`. \`tokens\` is THIS place's tokens only. Return an array of the same length whose entries provide derivatives for real-valued elements only (i.e. dx/dt, not the new value); integer, boolean, uuid, and string elements are discrete and remain unchanged by dynamics (they can be read from input tokens but never written). The equation's \`colorId\` MUST match every referencing place's \`colorId\`.
 - Place visualizer (\`place.visualizerCode\`): \`export default Visualization(({ tokens, parameters }) => <JSX/>)\`. Classic React runtime — do NOT import React, do NOT use \`<>…</>\` fragments, do NOT use hooks. Convention: return a sized \`<svg viewBox="0 0 W H">…</svg>\`.
 - Metric (\`metric.code\`): a plain function body — NOT a module, no \`export default\`, no wrapper. The only variable in scope is \`state\`. Must \`return\` a finite number. Example: \`return state.places.Infected.count / (state.places.Susceptible.count + state.places.Infected.count + state.places.Recovered.count);\`. \`parameters\` and \`scenario\` are NOT available inside metrics.
-- Scenario per_place initial state: \`content\` keys are place IDs; uncoloured values are expressions with \`parameters\` and \`scenario\` in scope; coloured values are row arrays in colour element order using numbers and booleans; uuid columns accept UUID strings (any other text converts deterministically to a UUID via UUIDv5).
+- Scenario per_place initial state: \`content\` keys are place IDs; uncoloured values are expressions with \`parameters\` and \`scenario\` in scope; coloured values are row arrays in colour element order using numbers and booleans; string columns take literal text; uuid columns accept UUID strings (any other text converts deterministically to a UUID via UUIDv5).
 - Scenario code-mode initial state: function body returning \`{ PlaceName: tokens }\` keyed by NAME (asymmetric with per_place IDs); unknown names are silently dropped.
 - Parameter access in any code surface: use \`parameters.<variableName>\` where \`<variableName>\` is the parameter's lower_snake_case \`variableName\` value (e.g. \`parameters.crash_threshold\`, never \`parameters.crashThreshold\`).
 

libs/@hashintel/petrinaut-core/src/clipboard/serialize.test.ts

@@ -494,7 +494,7 @@ describe("parseClipboardPayload", () => {
             name: "Token",
             iconSlug: "circle",
             displayColor: "#FF0000",
-            elements: [{ elementId: "e1", name: "val", type: "string" }],
+            elements: [{ elementId: "e1", name: "val", type: "complex" }],
           },
         ],
         differentialEquations: [],

libs/@hashintel/petrinaut-core/src/default-codes.ts

@@ -9,17 +9,23 @@ const defaultTokenAttributeSource = (
     case "integer":
     case "real":
       return "0";
+    case "string":
+      return '""';
     case "uuid":
       return "Uuid.generate()";
   }
 };
 
 export function generateDefaultVisualizerCode(type: Color): string {
-  return `// This function defines how to visualize the tokens in the place of type "${type.name}".
+  return `// This function defines how to visualize the tokens in the place of type "${
+    type.name
+  }".
 // It receives the current tokens and parameters.
 export default Visualization(({ tokens, parameters }) => {
   return <svg viewBox="0 0 800 600">
-    {tokens.map(({ ${type.elements.map((el) => el.name).join(", ")} }, index) => (
+    {tokens.map(({ ${type.elements
+      .map((el) => el.name)
+      .join(", ")} }, index) => (
       // Example: simple circle for each token
       <circle />
     ))}
@@ -47,7 +53,9 @@ export function generateDefaultDifferentialEquationCode(type: Color): string {
     }; // Example: all real-valued derivatives = 1`
       : `{}; // This type has no real-valued attributes; discrete values are unchanged by dynamics`;
 
-  return `// This function defines the differential equation for the place of type "${type.name}".
+  return `// This function defines the differential equation for the place of type "${
+    type.name
+  }".
 // The function receives the current tokens in this place and the parameters.
 // It should return derivatives for real-valued token attributes in this place.
 export default Dynamics((tokens, parameters) => {
@@ -90,7 +98,11 @@ export default Lambda((tokensByPlace, parameters) => {
   //  2. Infinity means always enabled
   //  3. Any other number is the average rate per second
 
-  ${lambdaType === "predicate" ? "return true; // Always enabled (alternative: return Infinity;)" : "return 1.0; // Average firing rate of once per second"}
+  ${
+    lambdaType === "predicate"
+      ? "return true; // Always enabled (alternative: return Infinity;)"
+      : "return 1.0; // Average firing rate of once per second"
+  }
 });`;
 
 export function generateDefaultTransitionKernelCode(
@@ -117,7 +129,9 @@ export default TransitionKernel((tokensByPlace, parameters) => {
       ${Array.from({ length: arc.weight })
         .map(
           () =>
-            `{ ${arc.type.elements.map((el) => `${el.name}: ${defaultTokenAttributeSource(el)}`).join(", ")} }`,
+            `{ ${arc.type.elements
+              .map((el) => `${el.name}: ${defaultTokenAttributeSource(el)}`)
+              .join(", ")} }`,
         )
         .join(",\n      ")}
     ],`,

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

@@ -174,6 +174,7 @@ export type {
   WorkerFactory,
   InitialMarking,
   InitialPlaceMarking,
+  InitialTokenAttributeValue,
   MonteCarloAdvanceResult,
   MonteCarloActiveRunPlaceCountsVisitor,
   MonteCarloExperiment,
@@ -342,10 +343,13 @@ export {
   encodeTokenToBytes,
   readTokenRecord,
   type PhysicalKind,
+  type StringPoolReader,
+  type StringPoolWriter,
   type TokenLayoutField,
   type TokenRegionViews,
   type TokenSlotLayout,
 } from "./simulation/engine/token-layout";
+export { StringPool } from "./simulation/engine/string-pool";
 export {
   formatUuid,
   isUuidString,

libs/@hashintel/petrinaut-core/src/lsp/lib/checker.test.ts

@@ -1116,6 +1116,117 @@ describe("checkSDCPN", () => {
     });
   });
 
+  describe("string elements", () => {
+    const stringTypes = [
+      {
+        id: "color1",
+        elements: [
+          { name: "label", type: "string" as const },
+          { name: "x", type: "real" as const },
+        ],
+      },
+    ];
+    const stringPlaces = [
+      { id: "place1", name: "Source", colorId: "color1" },
+      { id: "place2", name: "Target", colorId: "color1" },
+    ];
+    const stringKernel = (body: string) =>
+      createSDCPN({
+        types: stringTypes,
+        places: stringPlaces,
+        transitions: [
+          {
+            id: "t1",
+            inputArcs: [{ placeId: "place1", weight: 1, type: "standard" }],
+            outputArcs: [{ placeId: "place2", weight: 1 }],
+            transitionKernelCode: `export default TransitionKernel((input, parameters) => {
+              return { Target: [${body}] };
+            });`,
+          },
+        ],
+      });
+
+    it("types input string attributes as string (comparison and methods are valid)", () => {
+      const sdcpn = createSDCPN({
+        types: stringTypes,
+        places: stringPlaces,
+        transitions: [
+          {
+            id: "t1",
+            lambdaType: "predicate",
+            inputArcs: [{ placeId: "place1", weight: 1, type: "standard" }],
+            outputArcs: [{ placeId: "place2", weight: 1 }],
+            lambdaCode: `export default Lambda((input, parameters) => {
+              return input.Source[0].label === "queued" && input.Source[0].label.startsWith("q");
+            });`,
+            transitionKernelCode: `export default TransitionKernel((input, parameters) => {
+              return { Target: [input.Source[0]] };
+            });`,
+          },
+        ],
+      });
+
+      const result = check(sdcpn);
+
+      expect(result.isValid).toBe(true);
+      expect(result.itemDiagnostics).toHaveLength(0);
+    });
+
+    it("accepts plain string kernel outputs and forwarded input strings", () => {
+      const literal = check(stringKernel(`{ label: "shipped", x: 1 }`));
+      expect(literal.isValid).toBe(true);
+      expect(literal.itemDiagnostics).toHaveLength(0);
+
+      const forwarded = check(
+        stringKernel(`{ label: input.Source[0].label, x: input.Source[0].x }`),
+      );
+      expect(forwarded.isValid).toBe(true);
+      expect(forwarded.itemDiagnostics).toHaveLength(0);
+    });
+
+    it("rejects arithmetic on an input string attribute", () => {
+      const sdcpn = createSDCPN({
+        types: stringTypes,
+        places: stringPlaces,
+        transitions: [
+          {
+            id: "t1",
+            lambdaType: "predicate",
+            inputArcs: [{ placeId: "place1", weight: 1, type: "standard" }],
+            outputArcs: [{ placeId: "place2", weight: 1 }],
+            lambdaCode: `export default Lambda((input, parameters) => {
+              return input.Source[0].label * 2 > 0;
+            });`,
+            transitionKernelCode: `export default TransitionKernel((input, parameters) => {
+              return { Target: [input.Source[0]] };
+            });`,
+          },
+        ],
+      });
+
+      const result = check(sdcpn);
+
+      expect(result.isValid).toBe(false);
+      expect(result.itemDiagnostics[0]?.itemType).toBe("transition-lambda");
+    });
+
+    it("rejects Distribution values on string attributes", () => {
+      const result = check(
+        stringKernel(`{ label: Distribution.Uniform(0, 1), x: 1 }`),
+      );
+
+      expect(result.isValid).toBe(false);
+      expect(result.itemDiagnostics[0]?.itemType).toBe("transition-kernel");
+    });
+
+    it("rejects numeric values on string attributes", () => {
+      const result = check(stringKernel(`{ label: 42, x: 1 }`));
+
+      expect(result.isValid).toBe(false);
+      expect(result.itemDiagnostics[0]?.itemType).toBe("transition-kernel");
+    });
+  });
+
   describe("Multiple errors", () => {
     it("reports errors from multiple items", () => {
       // GIVEN - SDCPN with errors in both a differential equation and a transition