@holoscript/plugin-civil-engineering 2.0.1

package/src/runtime.ts

@@ -0,0 +1,207 @@
+/**
+ * Runtime integration for @holoscript/plugin-civil-engineering.
+ *
+ * Bridges the previously dead-wired `dsm_frame_2d` trait into a behavioral
+ * TraitHandler that the HoloScript runtime actually dispatches
+ * (HoloScriptRuntime.registerTrait -> applyDirectives / updateTraits).
+ *
+ * Before this module the plugin declared the trait NAME only
+ * (pluginMeta.traits) and exported the Direct-Stiffness-Method solver
+ * (`solveFrame2D`, `validateFrame2DModel`, `buildFrame2DReceipt`), but nothing
+ * invoked the solver THROUGH the runtime — the trait was built-but-dead-wired.
+ * This mirrors government-civic-plugin's reference integration (`civic_decision`
+ * -> mcdaAnalysis): it wires the deterministic DSM 2D frame solver
+ * (`solveFrame2D`) behind the `dsm_frame_2d` trait so the runtime's directive
+ * dispatch can run it.
+ */
+import { registerPluginTraits } from '@holoscript/core/runtime';
+import {
+  solveFrame2D,
+  validateFrame2DModel,
+  type Frame2DModel,
+  type Frame2DResult,
+} from './frame2d';
+
+/** Stable id for this plugin's trait ownership tagging. */
+export const CIVIL_ENGINEERING_PLUGIN_ID = 'civil-engineering' as const;
+
+/**
+ * Config carried by an orb's `@dsm_frame_2d` trait directive. Either supply a
+ * fully-formed `model`, or the `Frame2DModel` fields inline (the inline fields
+ * are assembled into a model). A missing/invalid model emits
+ * `dsm_frame_2d_error`.
+ */
+export interface DsmFrame2dTraitConfig {
+  /** Complete frame model to solve. Preferred form. */
+  model?: Frame2DModel;
+  /** Inline model id (used when `model` is omitted). */
+  id?: Frame2DModel['id'];
+  /** Inline nodes (used when `model` is omitted). */
+  nodes?: Frame2DModel['nodes'];
+  /** Inline elements (used when `model` is omitted). */
+  elements?: Frame2DModel['elements'];
+  /** Inline supports (used when `model` is omitted). */
+  supports?: Frame2DModel['supports'];
+  /** Inline nodal loads (used when `model` is omitted). */
+  nodalLoads?: Frame2DModel['nodalLoads'];
+  /** Inline distributed loads (used when `model` is omitted). */
+  distributedLoads?: Frame2DModel['distributedLoads'];
+}
+
+/** Summary payload emitted on `dsm_frame_2d_solved`. */
+export interface DsmFrame2dSolvedEvent {
+  nodeId: string;
+  /** Solver convergence flag. */
+  converged: boolean;
+  /** True if all element utilisation ratios < 1.0. */
+  structurallyAdequate: boolean;
+  /** Maximum absolute nodal displacement (m). */
+  maxDisplacementM: number;
+  /** Maximum element utilisation ratio. */
+  maxUtilisationRatio: number;
+  /** Per-node displacements (ux, uy, θz) recovered by the solver. */
+  nodeDisplacements: Frame2DResult['nodeDisplacements'];
+  /** Support reactions recovered by the solver. */
+  reactions: Frame2DResult['reactions'];
+  /** Node count in the solved model. */
+  nodeCount: number;
+  /** Element count in the solved model. */
+  elementCount: number;
+}
+
+/**
+ * Structural view of the runtime trait-handler contract. Matches
+ * `@holoscript/core` TraitTypes.TraitHandler at the call sites the runtime
+ * actually uses (onAttach / onUpdate receive the node, the directive config,
+ * and a context exposing `emit`). Declared locally so the plugin stays
+ * decoupled from core's full trait surface.
+ */
+export interface TraitDispatchContext {
+  emit: (event: string, payload?: unknown) => void;
+  setState?: (updates: Record<string, unknown>) => void;
+}
+
+export interface RuntimeTraitHandler {
+  name: string;
+  onAttach?: (node: unknown, config: DsmFrame2dTraitConfig, context: TraitDispatchContext) => void;
+  onUpdate?: (
+    node: unknown,
+    config: DsmFrame2dTraitConfig,
+    context: TraitDispatchContext,
+    delta: number,
+  ) => void;
+}
+
+interface DsmFrame2dNode {
+  id?: string;
+  name?: string;
+  properties?: Record<string, unknown>;
+  __frame2dResult?: Frame2DResult;
+}
+
+/** Resolve a `Frame2DModel` from the directive config (explicit model or inline fields). */
+function resolveModel(config: DsmFrame2dTraitConfig | undefined): Frame2DModel | undefined {
+  if (!config) return undefined;
+  if (config.model) return config.model;
+  if (config.nodes && config.elements && config.supports) {
+    return {
+      id: config.id ?? 'dsm_frame_2d',
+      nodes: config.nodes,
+      elements: config.elements,
+      supports: config.supports,
+      nodalLoads: config.nodalLoads,
+      distributedLoads: config.distributedLoads,
+    };
+  }
+  return undefined;
+}
+
+/** Run the DSM solver on the directive config, write the result onto the node, and emit. */
+function solveOntoNode(
+  node: unknown,
+  config: DsmFrame2dTraitConfig | undefined,
+  context: TraitDispatchContext,
+): void {
+  const carrier = node as DsmFrame2dNode;
+  const nodeId = carrier.id ?? carrier.name ?? 'unknown';
+
+  const model = resolveModel(config);
+  if (!model) {
+    context.emit('dsm_frame_2d_error', {
+      nodeId,
+      error:
+        'dsm_frame_2d trait requires config.model (Frame2DModel) or inline config.nodes + config.elements + config.supports',
+    });
+    return;
+  }
+
+  // Validate BEFORE solving so a malformed/under-constrained model surfaces a
+  // descriptive error instead of a bare "singular stiffness matrix" throw.
+  const validation = validateFrame2DModel(model);
+  if (!validation.valid) {
+    context.emit('dsm_frame_2d_error', {
+      nodeId,
+      error: `invalid frame model: ${validation.errors.join('; ')}`,
+      errors: validation.errors,
+    });
+    return;
+  }
+
+  try {
+    const result = solveFrame2D(model);
+    carrier.__frame2dResult = result;
+    carrier.properties = {
+      ...(carrier.properties ?? {}),
+      frame2dConverged: result.converged,
+      frame2dStructurallyAdequate: result.structurallyAdequate,
+      frame2dMaxDisplacementM: result.maxDisplacementM,
+      frame2dMaxUtilisationRatio: result.maxUtilisationRatio,
+    };
+    const summary: DsmFrame2dSolvedEvent = {
+      nodeId,
+      converged: result.converged,
+      structurallyAdequate: result.structurallyAdequate,
+      maxDisplacementM: result.maxDisplacementM,
+      maxUtilisationRatio: result.maxUtilisationRatio,
+      nodeDisplacements: result.nodeDisplacements,
+      reactions: result.reactions,
+      nodeCount: model.nodes.length,
+      elementCount: model.elements.length,
+    };
+    context.setState?.({ [`dsm_frame_2d:${nodeId}`]: summary });
+    context.emit('dsm_frame_2d_solved', summary);
+  } catch (error) {
+    context.emit('dsm_frame_2d_error', {
+      nodeId,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+/**
+ * Behavioral handler for the civil-engineering `dsm_frame_2d` trait. Runs the
+ * deterministic Direct-Stiffness-Method 2D frame solver whenever an orb carrying
+ * the trait is attached (and on each per-frame update), writing the result onto
+ * the node and emitting `dsm_frame_2d_solved` / `dsm_frame_2d_error`.
+ */
+export const dsmFrame2dHandler: RuntimeTraitHandler = {
+  name: 'dsm_frame_2d',
+  onAttach: (node, config, context) => solveOntoNode(node, config, context),
+  onUpdate: (node, config, context) => solveOntoNode(node, config, context),
+};
+
+/** A runtime that can register behavioral trait handlers. */
+export interface TraitRegistrar {
+  registerTrait(name: string, handler: unknown): void;
+}
+
+/**
+ * Register civil-engineering behavioral trait handlers into a runtime that
+ * exposes `registerTrait(name, handler)` — e.g. `@holoscript/core`
+ * HoloScriptRuntime. This is the consumption path the dead-wired tier was
+ * missing: after this call the runtime's directive dispatch (applyDirectives /
+ * updateTraits) will invoke the DSM frame solver for `@dsm_frame_2d` orbs.
+ */
+export function registerCivilEngineeringTraitHandlers(registrar: TraitRegistrar): void {
+  registerPluginTraits(registrar, CIVIL_ENGINEERING_PLUGIN_ID, [dsmFrame2dHandler]);
+}

package/src/traits/LoadBearingTrait.ts

@@ -0,0 +1,25 @@
+/** @load_bearing Trait — Load path and capacity tracking. @trait load_bearing */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type LoadType = 'dead' | 'live' | 'wind' | 'seismic' | 'snow' | 'impact' | 'thermal';
+export interface LoadCase { id: string; type: LoadType; magnitudeKN: number; direction: [number, number, number]; combinationFactor: number; }
+export interface LoadBearingConfig { capacityKN: number; loadCases: LoadCase[]; redundancyFactor: number; }
+export interface LoadBearingState { totalAppliedKN: number; remainingCapacityKN: number; criticalLoadCase: string | null; isOverloaded: boolean; }
+
+const defaultConfig: LoadBearingConfig = { capacityKN: 100, loadCases: [], redundancyFactor: 1.0 };
+
+export function createLoadBearingHandler(): TraitHandler<LoadBearingConfig> {
+  return { name: 'load_bearing', defaultConfig,
+    onAttach(n: HSPlusNode, c: LoadBearingConfig, ctx: TraitContext) {
+      const total = c.loadCases.reduce((sum, lc) => sum + lc.magnitudeKN * lc.combinationFactor, 0);
+      n.__loadState = { totalAppliedKN: total, remainingCapacityKN: c.capacityKN - total, criticalLoadCase: null, isOverloaded: total > c.capacityKN };
+      ctx.emit?.('load:assessed', { total, capacity: c.capacityKN });
+    },
+    onDetach(n: HSPlusNode, _c: LoadBearingConfig, ctx: TraitContext) { delete n.__loadState; ctx.emit?.('load:removed'); },
+    onUpdate() {},
+    onEvent(n: HSPlusNode, c: LoadBearingConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__loadState as LoadBearingState | undefined; if (!s) return;
+      if (e.type === 'load:add') { const kn = (e.payload?.magnitudeKN as number) ?? 0; s.totalAppliedKN += kn; s.remainingCapacityKN = c.capacityKN - s.totalAppliedKN; s.isOverloaded = s.totalAppliedKN > c.capacityKN; if (s.isOverloaded) ctx.emit?.('load:overloaded', { applied: s.totalAppliedKN, capacity: c.capacityKN }); }
+    },
+  };
+}

package/src/traits/MaterialFatigueTrait.ts

@@ -0,0 +1,28 @@
+/** @material_fatigue Trait — Fatigue life estimation. @trait material_fatigue */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export interface MaterialFatigueConfig { sNcurveSlope: number; enduranceLimitMPa: number; designLifeCycles: number; stressRatio: number; surfaceFinishFactor: number; }
+export interface MaterialFatigueState { accumulatedCycles: number; damageFraction: number; remainingLifePercent: number; isFailed: boolean; }
+
+const defaultConfig: MaterialFatigueConfig = { sNcurveSlope: -0.1, enduranceLimitMPa: 200, designLifeCycles: 1e6, stressRatio: -1, surfaceFinishFactor: 0.9 };
+
+export function createMaterialFatigueHandler(): TraitHandler<MaterialFatigueConfig> {
+  return { name: 'material_fatigue', defaultConfig,
+    onAttach(n: HSPlusNode, _c: MaterialFatigueConfig, ctx: TraitContext) { n.__fatigueState = { accumulatedCycles: 0, damageFraction: 0, remainingLifePercent: 100, isFailed: false }; ctx.emit?.('fatigue:monitoring_started'); },
+    onDetach(n: HSPlusNode, _c: MaterialFatigueConfig, ctx: TraitContext) { delete n.__fatigueState; ctx.emit?.('fatigue:monitoring_stopped'); },
+    onUpdate() {},
+    onEvent(n: HSPlusNode, c: MaterialFatigueConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__fatigueState as MaterialFatigueState | undefined; if (!s || s.isFailed) return;
+      if (e.type === 'fatigue:add_cycles') {
+        const cycles = (e.payload?.cycles as number) ?? 0;
+        const stressMPa = (e.payload?.stressAmplitudeMPa as number) ?? 0;
+        s.accumulatedCycles += cycles;
+        const nf = stressMPa > c.enduranceLimitMPa ? Math.pow(stressMPa / c.enduranceLimitMPa, 1 / c.sNcurveSlope) * c.designLifeCycles : Infinity;
+        s.damageFraction += cycles / nf;
+        s.remainingLifePercent = Math.max(0, (1 - s.damageFraction) * 100);
+        if (s.damageFraction >= 1) { s.isFailed = true; ctx.emit?.('fatigue:failure', { cycles: s.accumulatedCycles }); }
+        else ctx.emit?.('fatigue:updated', { damage: s.damageFraction, remaining: s.remainingLifePercent });
+      }
+    },
+  };
+}

package/src/traits/StructuralAnalysisTrait.ts

@@ -0,0 +1,28 @@
+/** @structural_analysis Trait — Finite element structural analysis. @trait structural_analysis */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type StructureType = 'beam' | 'column' | 'slab' | 'truss' | 'frame' | 'shell' | 'foundation';
+export type MaterialType = 'steel' | 'concrete' | 'timber' | 'masonry' | 'composite' | 'aluminum';
+export interface StructuralAnalysisConfig { structureType: StructureType; material: MaterialType; yieldStrengthMPa: number; elasticModulusGPa: number; safetyFactor: number; loadCasesCount: number; }
+export interface StructuralAnalysisState { maxStressMPa: number; maxDeflectionMm: number; utilizationRatio: number; isPasssing: boolean; }
+
+const defaultConfig: StructuralAnalysisConfig = { structureType: 'beam', material: 'steel', yieldStrengthMPa: 250, elasticModulusGPa: 200, safetyFactor: 1.5, loadCasesCount: 1 };
+
+export function createStructuralAnalysisHandler(): TraitHandler<StructuralAnalysisConfig> {
+  return { name: 'structural_analysis', defaultConfig,
+    onAttach(n: HSPlusNode, _c: StructuralAnalysisConfig, ctx: TraitContext) { n.__structState = { maxStressMPa: 0, maxDeflectionMm: 0, utilizationRatio: 0, isPasssing: true }; ctx.emit?.('structural:ready'); },
+    onDetach(n: HSPlusNode, _c: StructuralAnalysisConfig, ctx: TraitContext) { delete n.__structState; ctx.emit?.('structural:removed'); },
+    onUpdate() {},
+    onEvent(n: HSPlusNode, c: StructuralAnalysisConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__structState as StructuralAnalysisState | undefined; if (!s) return;
+      if (e.type === 'structural:analyze') {
+        const loadKN = (e.payload?.loadKN as number) ?? 0;
+        const spanM = (e.payload?.spanM as number) ?? 1;
+        s.maxStressMPa = (loadKN * 1000 * spanM) / (0.001 * c.elasticModulusGPa * 1e9) * 1e6;
+        s.utilizationRatio = s.maxStressMPa / (c.yieldStrengthMPa / c.safetyFactor);
+        s.isPasssing = s.utilizationRatio <= 1.0;
+        ctx.emit?.('structural:result', { stress: s.maxStressMPa, utilization: s.utilizationRatio, pass: s.isPasssing });
+      }
+    },
+  };
+}

package/src/traits/types.ts

@@ -0,0 +1,4 @@
+export interface HSPlusNode { id?: string; properties?: Record<string, unknown>; [key: string]: unknown; }
+export interface TraitContext { emit?: (event: string, payload?: unknown) => void; [key: string]: unknown; }
+export interface TraitEvent { type: string; payload?: Record<string, unknown>; [key: string]: unknown; }
+export interface TraitHandler<T = unknown> { name: string; defaultConfig: T; onAttach(n: HSPlusNode, c: T, ctx: TraitContext): void; onDetach(n: HSPlusNode, c: T, ctx: TraitContext): void; onUpdate(n: HSPlusNode, c: T, ctx: TraitContext, d: number): void; onEvent(n: HSPlusNode, c: T, ctx: TraitContext, e: TraitEvent): void; }

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../../tsconfig.json", "compilerOptions": { "outDir": "dist", "rootDir": "src", "declaration": true }, "include": ["src"] }

package/vitest.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from 'vitest/config';
+import { resolve } from 'path';
+
+// resolve.alias is REQUIRED: without it, `@holoscript/core/runtime` resolves to
+// the STALE built dist and registerPluginTraits is missing ("not a function").
+// Point the subpath imports at core/engine source so the runtime barrel
+// (core/src/runtime.ts) and shared registrar resolve from source. Mirrors
+// government-civic-plugin/vitest.config.ts.
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@holoscript/engine': resolve(__dirname, '../../engine/src'),
+      '@holoscript/core': resolve(__dirname, '../../core/src'),
+    },
+  },
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    passWithNoTests: true,
+  },
+});