@holoscript/plugin-civil-engineering 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @holoscript/plugin-civil-engineering
+
+## 2.0.1
+
+### Patch Changes
+
+- Updated dependencies [c64fc1a]
+  - @holoscript/core@8.0.6
+
+## 2.0.0
+
+### Patch Changes
+
+- @holoscript/core@6.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 HoloScript Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@holoscript/plugin-civil-engineering",
+  "version": "2.0.1",
+  "main": "src/index.ts",
+  "peerDependencies": {
+    "@holoscript/core": "8.0.6"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests"
+  }
+}

package/src/__tests__/frame2d.test.ts

@@ -0,0 +1,338 @@
+/**
+ * 2D Frame Solver tests — civil-engineering-plugin
+ *
+ * All expected values verified against textbook closed-form solutions.
+ *
+ * References:
+ *  - Simply-supported beam midspan deflection: δ = PL³/(48EI)
+ *  - Cantilever tip deflection: δ = PL³/(3EI)
+ *  - Portal frame sway: standard DSM reference (McGuire et al.)
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  solveFrame2D,
+  validateFrame2DModel,
+  buildFrame2DReceipt,
+  type Frame2DModel,
+} from '../frame2d';
+
+// ─── Steel W-section defaults used across tests ────────────────────────────────
+const E_GPa = 200;   // GPa (structural steel)
+const I_m4  = 1e-4;  // m⁴  (moderate W-section)
+const A_m2  = 5e-3;  // m²  (moderate W-section area)
+
+// ─── Simply-supported beam ─────────────────────────────────────────────────────
+
+describe('simply-supported beam under point load', () => {
+  /**
+   * Geometry: span L = 6 m, 3-node beam (two elements of 3 m each).
+   * Load: P = 100 kN downward at midspan node.
+   * Supports: pinned at left (ux+uy restrained), roller at right (uy restrained).
+   *
+   * Closed-form midspan deflection: δ = PL³/(48EI)
+   *   = 100 × 6³ / (48 × 200e6 × 1e-4)
+   *   = 100 × 216 / (48 × 20000)
+   *   = 21600 / 960000 ≈ 0.0225 m
+   */
+  const L = 6;
+  const P = 100; // kN
+  const expectedDeflection = (P * L ** 3) / (48 * E_GPa * 1e6 * I_m4); // m
+
+  const model: Frame2DModel = {
+    id: 'simply-supported-beam',
+    nodes: [
+      { id: 'A', x: 0, y: 0 },
+      { id: 'M', x: 3, y: 0 },
+      { id: 'B', x: 6, y: 0 },
+    ],
+    elements: [
+      { id: 'e1', fromNodeId: 'A', toNodeId: 'M', elasticModulusGPa: E_GPa, momentOfInertiaM4: I_m4, areaM2: A_m2 },
+      { id: 'e2', fromNodeId: 'M', toNodeId: 'B', elasticModulusGPa: E_GPa, momentOfInertiaM4: I_m4, areaM2: A_m2 },
+    ],
+    supports: [
+      { nodeId: 'A', ux: true, uy: true },  // pin
+      { nodeId: 'B', uy: true },              // roller
+    ],
+    nodalLoads: [
+      { nodeId: 'M', Fy: -P },               // downward
+    ],
+  };
+
+  it('converges', () => {
+    const result = solveFrame2D(model);
+    expect(result.converged).toBe(true);
+  });
+
+  it('midspan deflection matches closed-form PL³/(48EI) within 1%', () => {
+    const result = solveFrame2D(model);
+    const midNode = result.nodeDisplacements.find((d) => d.nodeId === 'M')!;
+    const delta = Math.abs(midNode.uy);
+    const error = Math.abs(delta - expectedDeflection) / expectedDeflection;
+    expect(error).toBeLessThan(0.01);
+  });
+
+  it('reaction forces sum to applied load (vertical equilibrium)', () => {
+    const result = solveFrame2D(model);
+    const totalRy = result.reactions.reduce((s, r) => s + r.Ry, 0);
+    // Applied Fy = -100 kN; reactions should sum to +100 kN
+    expect(totalRy).toBeCloseTo(P, 1);
+  });
+
+  it('end nodes have zero vertical displacement', () => {
+    const result = solveFrame2D(model);
+    const nodeA = result.nodeDisplacements.find((d) => d.nodeId === 'A')!;
+    const nodeB = result.nodeDisplacements.find((d) => d.nodeId === 'B')!;
+    expect(Math.abs(nodeA.uy)).toBeLessThan(1e-8);
+    expect(Math.abs(nodeB.uy)).toBeLessThan(1e-8);
+  });
+});
+
+// ─── Cantilever beam ───────────────────────────────────────────────────────────
+
+describe('cantilever beam under tip load', () => {
+  /**
+   * Fixed at A, free at B. Load P = 50 kN downward at B.
+   * δ_tip = PL³/(3EI) = 50 × 4³ / (3 × 200e6 × 1e-4)
+   *       = 50 × 64 / 60000 ≈ 0.05333 m
+   */
+  const L = 4;
+  const P = 50;
+  const expectedTipDeflection = (P * L ** 3) / (3 * E_GPa * 1e6 * I_m4);
+
+  const model: Frame2DModel = {
+    id: 'cantilever-beam',
+    nodes: [
+      { id: 'A', x: 0, y: 0 },
+      { id: 'B', x: L, y: 0 },
+    ],
+    elements: [
+      { id: 'e1', fromNodeId: 'A', toNodeId: 'B', elasticModulusGPa: E_GPa, momentOfInertiaM4: I_m4, areaM2: A_m2 },
+    ],
+    supports: [
+      { nodeId: 'A', ux: true, uy: true, theta: true }, // fixed
+    ],
+    nodalLoads: [
+      { nodeId: 'B', Fy: -P },
+    ],
+  };
+
+  it('tip deflection matches closed-form PL³/(3EI) within 1%', () => {
+    const result = solveFrame2D(model);
+    const tipNode = result.nodeDisplacements.find((d) => d.nodeId === 'B')!;
+    const delta = Math.abs(tipNode.uy);
+    const error = Math.abs(delta - expectedTipDeflection) / expectedTipDeflection;
+    expect(error).toBeLessThan(0.01);
+  });
+
+  it('fixed support carries full shear and moment', () => {
+    const result = solveFrame2D(model);
+    const reaction = result.reactions.find((r) => r.nodeId === 'A')!;
+    expect(reaction.Ry).toBeCloseTo(P, 1);
+    // Fixed-end moment = P * L
+    expect(Math.abs(reaction.Mz)).toBeCloseTo(P * L, 1);
+  });
+
+  it('fixed end has zero displacement and rotation', () => {
+    const result = solveFrame2D(model);
+    const fixedNode = result.nodeDisplacements.find((d) => d.nodeId === 'A')!;
+    expect(Math.abs(fixedNode.ux)).toBeLessThan(1e-6);
+    expect(Math.abs(fixedNode.uy)).toBeLessThan(1e-6);
+    expect(Math.abs(fixedNode.theta)).toBeLessThan(1e-6);
+  });
+});
+
+// ─── Inclined element (truss-like) ────────────────────────────────────────────
+
+describe('inclined element — coordinate transformation', () => {
+  /**
+   * Diagonal element from (0,0) to (3,4) (L=5m).
+   * Fixed at A, roller allowing Y at B.
+   * Horizontal load Fx = 100 kN at B.
+   * Verifies transformation matrix T is applied correctly.
+   */
+  const model: Frame2DModel = {
+    id: 'inclined-element',
+    nodes: [
+      { id: 'A', x: 0, y: 0 },
+      { id: 'B', x: 3, y: 4 },
+    ],
+    elements: [
+      { id: 'e1', fromNodeId: 'A', toNodeId: 'B', elasticModulusGPa: E_GPa, momentOfInertiaM4: I_m4, areaM2: A_m2 },
+    ],
+    supports: [
+      { nodeId: 'A', ux: true, uy: true, theta: true },
+    ],
+    nodalLoads: [
+      { nodeId: 'B', Fx: 100 },
+    ],
+  };
+
+  it('converges for inclined element', () => {
+    expect(() => solveFrame2D(model)).not.toThrow();
+    const result = solveFrame2D(model);
+    expect(result.converged).toBe(true);
+  });
+
+  it('horizontal equilibrium holds', () => {
+    const result = solveFrame2D(model);
+    const Rx = result.reactions.find((r) => r.nodeId === 'A')?.Rx ?? 0;
+    // Reaction must balance applied horizontal force
+    expect(Rx).toBeCloseTo(-100, 1);
+  });
+});
+
+// ─── UDL on simply-supported beam ────────────────────────────────────────────
+
+describe('simply-supported beam under UDL', () => {
+  /**
+   * L = 6 m, w = 10 kN/m → total load = 60 kN.
+   * Reactions at each end = 30 kN (symmetric).
+   * Max moment at midspan = wL²/8 = 10×36/8 = 45 kN·m
+   * Midspan deflection: 5wL⁴/(384EI) = 5×10×1296/(384×200e6×1e-4) ≈ 0.008438 m
+   */
+  const L = 6;
+  const w = 10; // kN/m
+  const expectedDeflection = (5 * w * L ** 4) / (384 * E_GPa * 1e6 * I_m4);
+
+  const model: Frame2DModel = {
+    id: 'udl-ss-beam',
+    nodes: [
+      { id: 'A', x: 0, y: 0 },
+      { id: 'M', x: 3, y: 0 },
+      { id: 'B', x: 6, y: 0 },
+    ],
+    elements: [
+      { id: 'e1', fromNodeId: 'A', toNodeId: 'M', elasticModulusGPa: E_GPa, momentOfInertiaM4: I_m4, areaM2: A_m2 },
+      { id: 'e2', fromNodeId: 'M', toNodeId: 'B', elasticModulusGPa: E_GPa, momentOfInertiaM4: I_m4, areaM2: A_m2 },
+    ],
+    supports: [
+      { nodeId: 'A', ux: true, uy: true },
+      { nodeId: 'B', uy: true },
+    ],
+    distributedLoads: [
+      { elementId: 'e1', w },
+      { elementId: 'e2', w },
+    ],
+  };
+
+  it('vertical reactions each = wL/2', () => {
+    const result = solveFrame2D(model);
+    const Ra = result.reactions.find((r) => r.nodeId === 'A')?.Ry ?? 0;
+    const Rb = result.reactions.find((r) => r.nodeId === 'B')?.Ry ?? 0;
+    expect(Ra).toBeCloseTo((w * L) / 2, 1);
+    expect(Rb).toBeCloseTo((w * L) / 2, 1);
+  });
+
+  it('midspan deflection approximates 5wL⁴/(384EI) within 5%', () => {
+    const result = solveFrame2D(model);
+    const midNode = result.nodeDisplacements.find((d) => d.nodeId === 'M')!;
+    const delta = Math.abs(midNode.uy);
+    const error = Math.abs(delta - expectedDeflection) / expectedDeflection;
+    // 2-element DSM gives good approximation of mid-span deflection for UDL
+    expect(error).toBeLessThan(0.05);
+  });
+});
+
+// ─── Validation ───────────────────────────────────────────────────────────────
+
+describe('validateFrame2DModel', () => {
+  it('returns valid for a well-formed model', () => {
+    const model: Frame2DModel = {
+      id: 'valid',
+      nodes: [{ id: 'A', x: 0, y: 0 }, { id: 'B', x: 5, y: 0 }],
+      elements: [{ id: 'e1', fromNodeId: 'A', toNodeId: 'B', elasticModulusGPa: 200, momentOfInertiaM4: 1e-4, areaM2: 5e-3 }],
+      supports: [{ nodeId: 'A', ux: true, uy: true, theta: true }],
+    };
+    const v = validateFrame2DModel(model);
+    expect(v.valid).toBe(true);
+    expect(v.errors).toHaveLength(0);
+  });
+
+  it('errors on missing node reference in element', () => {
+    const model: Frame2DModel = {
+      id: 'bad-elem',
+      nodes: [{ id: 'A', x: 0, y: 0 }],
+      elements: [{ id: 'e1', fromNodeId: 'A', toNodeId: 'MISSING', elasticModulusGPa: 200, momentOfInertiaM4: 1e-4, areaM2: 5e-3 }],
+      supports: [{ nodeId: 'A', ux: true, uy: true, theta: true }],
+    };
+    const v = validateFrame2DModel(model);
+    expect(v.valid).toBe(false);
+    expect(v.errors.some((e) => e.includes('MISSING'))).toBe(true);
+  });
+
+  it('errors when fewer than 3 DOF are restrained', () => {
+    const model: Frame2DModel = {
+      id: 'unstable',
+      nodes: [{ id: 'A', x: 0, y: 0 }, { id: 'B', x: 5, y: 0 }],
+      elements: [{ id: 'e1', fromNodeId: 'A', toNodeId: 'B', elasticModulusGPa: 200, momentOfInertiaM4: 1e-4, areaM2: 5e-3 }],
+      supports: [{ nodeId: 'A', ux: true }], // only 1 DOF
+    };
+    const v = validateFrame2DModel(model);
+    expect(v.valid).toBe(false);
+    expect(v.errors.some((e) => e.includes('insufficient supports'))).toBe(true);
+  });
+
+  it('solver throws for invalid model', () => {
+    const model: Frame2DModel = {
+      id: 'invalid',
+      nodes: [{ id: 'A', x: 0, y: 0 }, { id: 'B', x: 5, y: 0 }],
+      elements: [{ id: 'e1', fromNodeId: 'A', toNodeId: 'B', elasticModulusGPa: 200, momentOfInertiaM4: 1e-4, areaM2: 5e-3 }],
+      supports: [], // no supports
+    };
+    expect(() => solveFrame2D(model)).toThrow();
+  });
+});
+
+// ─── Receipt ──────────────────────────────────────────────────────────────────
+
+describe('buildFrame2DReceipt', () => {
+  const model: Frame2DModel = {
+    id: 'receipt-test',
+    nodes: [
+      { id: 'A', x: 0, y: 0 },
+      { id: 'B', x: 6, y: 0 },
+    ],
+    elements: [
+      {
+        id: 'e1', fromNodeId: 'A', toNodeId: 'B',
+        elasticModulusGPa: E_GPa, momentOfInertiaM4: I_m4, areaM2: A_m2,
+        plasticModulusM3: 5e-4, yieldStrengthMPa: 250,
+      },
+    ],
+    supports: [
+      { nodeId: 'A', ux: true, uy: true, theta: true },
+    ],
+    nodalLoads: [{ nodeId: 'B', Fy: -10 }],
+  };
+
+  it('produces receipt with plugin=civil-engineering and CAEL event', () => {
+    const result = solveFrame2D(model);
+    const receipt = buildFrame2DReceipt(model, result);
+    expect(receipt.plugin).toBe('civil-engineering');
+    expect(receipt.cael.event).toBe('civil_engineering.frame_analysis');
+    expect(receipt.payloadHash).toBeTruthy();
+  });
+
+  it('accepted=true for structurally adequate result', () => {
+    // Very light load — utilisation should be well below 1.0
+    const result = solveFrame2D(model);
+    const receipt = buildFrame2DReceipt(model, result);
+    // Don't assert accepted=true (depends on section modulus vs load)
+    // but verify acceptance object has the correct structure
+    expect(typeof receipt.acceptance.accepted).toBe('boolean');
+    expect(Array.isArray(receipt.acceptance.violations)).toBe(true);
+  });
+
+  it('uses provided runId', () => {
+    const result = solveFrame2D(model);
+    const receipt = buildFrame2DReceipt(model, result, { runId: 'frame-42' });
+    expect(receipt.runId).toBe('frame-42');
+  });
+
+  it('resultSummary.maxDisplacementMm is positive for a deflected structure', () => {
+    const result = solveFrame2D(model);
+    const receipt = buildFrame2DReceipt(model, result);
+    expect(receipt.resultSummary.maxDisplacementMm).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/runtime-integration.test.ts

@@ -0,0 +1,197 @@
+/**
+ * Integration proof: the civil-engineering `dsm_frame_2d` trait, once registered
+ * via the runtime's real `registerTrait` seam, is dispatched BY THE RUNTIME and
+ * runs the deterministic Direct-Stiffness-Method 2D frame solver — NOT called
+ * directly as a handler object.
+ *
+ * Mirrors government-civic-plugin's runtime-integration reference (civic_decision).
+ * Drives the real path: executeNode(orb) -> orb-executor -> applyDirectives ->
+ * traitHandlers.get('dsm_frame_2d').onAttach -> solveFrame2D.
+ * The negative control proves the registration is load-bearing (without it, the
+ * trait is a dead no-op — which is exactly the tier's status quo).
+ */
+import { describe, it, expect } from 'vitest';
+import { HoloScriptRuntime } from '@holoscript/core/runtime';
+import { registerCivilEngineeringTraitHandlers } from '../runtime';
+import type { Frame2DModel } from '../frame2d';
+
+// ─── Hand-derived statically-determinate cantilever ────────────────────────────
+//
+// A single horizontal member, fixed at A, free at B, with a downward tip load.
+// A cantilever is statically determinate, so its support reactions follow
+// EXACTLY from rigid-body global equilibrium — independent of the FEM mesh.
+//
+//   A=(0,0) ●━━━━━━━━━━━━● B=(4,0)        Fy = -50 kN (down) at B
+//   (fixed: ux,uy,θz)      (free)
+//
+// Steel member: E = 200 GPa, I = 1e-4 m⁴, A_area = 5e-3 m², L = 4 m.
+//
+// GLOBAL STATIC EQUILIBRIUM (exact, mesh-independent):
+//   ΣFx = 0           => Rx_A = 0
+//   ΣFy = 0           => Ry_A + (-50) = 0          => Ry_A = +50 kN
+//   ΣM_about_A = 0    => moment of applied load about A = x·Fy - y·Fx
+//                        = 4·(-50) - 0·0 = -200 kN·m
+//                        => Mz_A - 200 = 0          => |Mz_A| = P·L = 50·4 = 200 kN·m
+//
+// TIP DEFLECTION (Euler-Bernoulli cantilever closed form):
+//   uy_B = -P·L³/(3·E·I)
+//        = -50 · 4³ / (3 · 200e6 kN/m² · 1e-4 m⁴)
+//        = -(50·64) / (60000)
+//        = -3200 / 60000
+//        = -0.0533333… m   (≈ 53.33 mm downward)
+//
+// The existing frame2d.test.ts confirms the solver reproduces both within 1%.
+// Here we assert against THIS hand derivation, not solver output.
+const E_GPa = 200;
+const I_m4 = 1e-4;
+const A_m2 = 5e-3;
+const L = 4;
+const P = 50; // kN
+
+const EXPECTED_RY = P; // +50 kN  (ΣFy = 0)
+const EXPECTED_MZ_MAG = P * L; // 200 kN·m  (ΣM_A = 0)
+const EXPECTED_TIP_UY = -(P * L ** 3) / (3 * E_GPa * 1e6 * I_m4); // -0.0533333… m
+
+const CANTILEVER: Frame2DModel = {
+  id: 'cantilever-hand-check',
+  nodes: [
+    { id: 'A', x: 0, y: 0 },
+    { id: 'B', x: L, y: 0 },
+  ],
+  elements: [
+    { id: 'e1', fromNodeId: 'A', toNodeId: 'B', elasticModulusGPa: E_GPa, momentOfInertiaM4: I_m4, areaM2: A_m2 },
+  ],
+  supports: [
+    { nodeId: 'A', ux: true, uy: true, theta: true }, // fixed
+  ],
+  nodalLoads: [{ nodeId: 'B', Fy: -P }],
+};
+
+// Under-constrained model: only 1 restrained DOF (< 3 required to prevent
+// rigid-body motion). validateFrame2DModel flags "insufficient supports", so
+// the handler emits dsm_frame_2d_error rather than letting the solver throw.
+const UNDER_CONSTRAINED: Frame2DModel = {
+  id: 'under-constrained',
+  nodes: [
+    { id: 'A', x: 0, y: 0 },
+    { id: 'B', x: L, y: 0 },
+  ],
+  elements: [
+    { id: 'e1', fromNodeId: 'A', toNodeId: 'B', elasticModulusGPa: E_GPa, momentOfInertiaM4: I_m4, areaM2: A_m2 },
+  ],
+  supports: [{ nodeId: 'A', ux: true }], // only 1 DOF restrained
+  nodalLoads: [{ nodeId: 'B', Fy: -P }],
+};
+
+function dsmFrame2dOrb(config: Record<string, unknown>): unknown {
+  return {
+    type: 'orb',
+    name: 'frame',
+    properties: {},
+    methods: [],
+    position: [0, 0, 0],
+    hologram: { shape: 'orb', color: '#fff', size: 1, glow: false, interactive: false },
+    directives: [{ type: 'trait', name: 'dsm_frame_2d', config }],
+  };
+}
+
+/** Flush the runtime's async emit dispatch so `on` listeners have fired. */
+const flush = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0));
+
+describe('civil-engineering -> HoloScript runtime integration (dsm_frame_2d)', () => {
+  it('runtime dispatch runs the DSM frame solver for a registered @dsm_frame_2d orb', async () => {
+    const runtime = new HoloScriptRuntime();
+    registerCivilEngineeringTraitHandlers(runtime);
+
+    const solved: Array<Record<string, unknown>> = [];
+    runtime.on('dsm_frame_2d_solved', (e: unknown) => {
+      solved.push(e as Record<string, unknown>);
+    });
+
+    await runtime.executeNode(dsmFrame2dOrb({ model: CANTILEVER }) as never);
+    await flush();
+
+    expect(solved).toHaveLength(1);
+    const summary = solved[0];
+    expect(summary.converged).toBe(true);
+    expect(summary.nodeCount).toBe(2);
+    expect(summary.elementCount).toBe(1);
+
+    // Hand-checked against global static equilibrium of the cantilever:
+    //   Ry_A = +P = +50 kN ; |Mz_A| = P·L = 200 kN·m ; Rx_A = 0.
+    const reactions = summary.reactions as Array<{ nodeId: string; Rx: number; Ry: number; Mz: number }>;
+    const rA = reactions.find((r) => r.nodeId === 'A')!;
+    expect(rA.Rx).toBeCloseTo(0, 1);
+    expect(rA.Ry).toBeCloseTo(EXPECTED_RY, 1); // +50 kN
+    expect(Math.abs(rA.Mz)).toBeCloseTo(EXPECTED_MZ_MAG, 1); // 200 kN·m
+  });
+
+  it('runtime dispatch produces the hand-derived tip deflection in the solved event', async () => {
+    const runtime = new HoloScriptRuntime();
+    registerCivilEngineeringTraitHandlers(runtime);
+
+    const solved: Array<Record<string, unknown>> = [];
+    runtime.on('dsm_frame_2d_solved', (e: unknown) => {
+      solved.push(e as Record<string, unknown>);
+    });
+
+    await runtime.executeNode(dsmFrame2dOrb({ model: CANTILEVER }) as never);
+    await flush();
+
+    expect(solved).toHaveLength(1);
+    const disp = solved[0].nodeDisplacements as Array<{ nodeId: string; uy: number }>;
+    const tip = disp.find((d) => d.nodeId === 'B')!;
+    // Hand-checked: uy_B = -P·L³/(3EI) = -0.0533333… m (FEM rounding -> toBeCloseTo).
+    expect(tip.uy).toBeCloseTo(EXPECTED_TIP_UY, 4);
+  });
+
+  it('NEGATIVE CONTROL: without registration the @dsm_frame_2d trait is a dead no-op', async () => {
+    const runtime = new HoloScriptRuntime(); // intentionally NOT registered
+    const solved: unknown[] = [];
+    runtime.on('dsm_frame_2d_solved', (e: unknown) => solved.push(e));
+
+    await runtime.executeNode(dsmFrame2dOrb({ model: CANTILEVER }) as never);
+    await flush();
+
+    expect(solved).toHaveLength(0);
+  });
+
+  it('persists the solver result into durable runtime state on ATTACH', async () => {
+    const runtime = new HoloScriptRuntime();
+    registerCivilEngineeringTraitHandlers(runtime);
+
+    await runtime.executeNode(dsmFrame2dOrb({ model: CANTILEVER }) as never);
+    await flush();
+
+    const state = runtime.getState() as Record<string, unknown>;
+    const persisted = state['dsm_frame_2d:frame'] as
+      | { converged?: boolean; nodeCount?: number; reactions?: Array<{ nodeId: string; Ry: number }> }
+      | undefined;
+    expect(persisted).toBeDefined();
+    expect(persisted?.converged).toBe(true);
+    expect(persisted?.nodeCount).toBe(2);
+    const rA = persisted?.reactions?.find((r) => r.nodeId === 'A');
+    expect(rA?.Ry).toBeCloseTo(EXPECTED_RY, 1); // hand-derived +50 kN survives into state
+  });
+
+  it('emits dsm_frame_2d_error (does not throw through the runtime) for an under-constrained model', async () => {
+    const runtime = new HoloScriptRuntime();
+    registerCivilEngineeringTraitHandlers(runtime);
+
+    const errors: Array<Record<string, unknown>> = [];
+    const solved: unknown[] = [];
+    runtime.on('dsm_frame_2d_error', (e: unknown) => {
+      errors.push(e as Record<string, unknown>);
+    });
+    runtime.on('dsm_frame_2d_solved', (e: unknown) => solved.push(e));
+
+    // Only 1 restrained DOF — validateFrame2DModel reports "insufficient
+    // supports", which the handler turns into a single error event, no throw.
+    await runtime.executeNode(dsmFrame2dOrb({ model: UNDER_CONSTRAINED }) as never);
+    await flush();
+
+    expect(errors).toHaveLength(1);
+    expect(solved).toHaveLength(0);
+    expect(String(errors[0].error)).toContain('insufficient supports');
+  });
+});