@holoscript/plugin-retail-ecommerce 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @holoscript/plugin-retail-ecommerce
+
+## 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,14 @@
+{
+  "name": "@holoscript/plugin-retail-ecommerce",
+  "version": "2.0.1",
+  "description": "HoloScript domain plugin for retail-ecommerce",
+  "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__/retailsolver.test.ts

@@ -0,0 +1,324 @@
+/**
+ * Retail & e-commerce solver tests — retail-ecommerce-plugin
+ *
+ * Reference values verified against:
+ *  - Harris FW (1913) Operations and Cost — EOQ formula
+ *  - Philips RL (2005) Pricing and Revenue Optimization — elasticity
+ *  - CLV standard industry formulas (AGSM)
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  economicOrderQuantity,
+  priceOptimization,
+  markdownOptimization,
+  customerLifetimeValue,
+  conversionFunnelAnalysis,
+  abcClassification,
+  inventoryMetrics,
+  buildRetailReceipt,
+} from '../retailsolver';
+
+// ─── EOQ ─────────────────────────────────────────────────────────────────────
+
+describe('economicOrderQuantity', () => {
+  /**
+   * Classic EOQ example: D=1000, S=$10, H=$2.50/unit/yr
+   * EOQ = √(2×1000×10/2.5) = √8000 ≈ 89.44
+   * Orders/year = 1000/89.44 ≈ 11.18
+   * TAC = (1000/89.44)×10 + (89.44/2)×2.5 ≈ $223.61
+   */
+  it('EOQ = √(2DS/H)', () => {
+    const r = economicOrderQuantity(1000, 10, 2.5);
+    expect(r.eoq).toBeCloseTo(Math.sqrt(2 * 1000 * 10 / 2.5), 1);
+  });
+
+  it('ordersPerYear = demand / EOQ', () => {
+    const r = economicOrderQuantity(1000, 10, 2.5);
+    expect(r.ordersPerYear).toBeCloseTo(1000 / r.eoq, 4);
+  });
+
+  it('TAC = (D/EOQ)×S + (EOQ/2)×H', () => {
+    const r = economicOrderQuantity(1000, 10, 2.5);
+    const expected = (1000 / r.eoq) * 10 + (r.eoq / 2) * 2.5;
+    expect(r.totalAnnualCost).toBeCloseTo(expected, 1);
+  });
+
+  it('reorder point = daily demand × lead time', () => {
+    const r = economicOrderQuantity(2500, 50, 5, 5, 250);
+    // Daily demand = 2500/250 = 10, leadTime = 5 → ROP = 50
+    expect(r.reorderPoint).toBeCloseTo(50, 4);
+  });
+
+  it('higher ordering cost → higher EOQ', () => {
+    const r1 = economicOrderQuantity(1000, 10, 2.5);
+    const r2 = economicOrderQuantity(1000, 50, 2.5);
+    expect(r2.eoq).toBeGreaterThan(r1.eoq);
+  });
+
+  it('throws for zero annual demand', () => {
+    expect(() => economicOrderQuantity(0, 10, 2.5)).toThrow();
+  });
+
+  it('throws for zero holding cost', () => {
+    expect(() => economicOrderQuantity(1000, 10, 0)).toThrow();
+  });
+});
+
+// ─── Price optimization ───────────────────────────────────────────────────────
+
+describe('priceOptimization', () => {
+  /**
+   * Elastic demand: ε = -2 (elastic)
+   * Profit-maximizing price should be found via ternary search.
+   * With variable cost = 0: dπ/dP = Q(1 + 1/ε) = 0 → P* = P₀/(1+1/ε) ... but with variable cost = 0 and elasticity=-2, revenue is maximized at a price where MR=0.
+   */
+  it('elastic demand (ε=-2): revenue maximized by lower price', () => {
+    // With ε=-2, revenue decreasing above current price → optimal < current
+    const r = priceOptimization(100, 1000, -2);
+    // Optimal price should give higher revenue than current in elastic region
+    expect(r.optimalRevenue).toBeGreaterThanOrEqual(r.currentRevenue - 0.01);
+  });
+
+  it('optimalRevenue is positive and finite', () => {
+    // Solver maximizes PROFIT (not revenue); with variableCost=20, inelastic ε=-1.5
+    // raises price above $50 → higher margin but lower revenue. Revenue need not be ≥ current.
+    const r = priceOptimization(50, 500, -1.5, 20);
+    expect(r.optimalRevenue).toBeGreaterThan(0);
+    expect(Number.isFinite(r.optimalRevenue)).toBe(true);
+    expect(r.optimalPrice).toBeGreaterThan(0);
+  });
+
+  it('priceDemandCurve has 21 points', () => {
+    const r = priceOptimization(100, 500, -1.5);
+    expect(r.priceDemandCurve).toHaveLength(21);
+  });
+
+  it('demand decreases as price increases (law of demand)', () => {
+    const r = priceOptimization(100, 500, -1.5);
+    const curve = r.priceDemandCurve;
+    for (let i = 1; i < curve.length; i++) {
+      expect(curve[i].demand).toBeLessThanOrEqual(curve[i - 1].demand + 0.01);
+    }
+  });
+
+  it('throws for non-negative elasticity', () => {
+    expect(() => priceOptimization(100, 500, 0)).toThrow();
+  });
+
+  it('throws for zero current demand', () => {
+    expect(() => priceOptimization(100, 0, -1.5)).toThrow();
+  });
+});
+
+// ─── Markdown optimization ────────────────────────────────────────────────────
+
+describe('markdownOptimization', () => {
+  it('schedule has same number of entries as markdownSteps', () => {
+    const r = markdownOptimization(100, 500, 90, 5, -2.0);
+    expect(r.schedule).toHaveLength(4); // default 4 steps
+  });
+
+  it('prices decrease with each markdown step', () => {
+    const r = markdownOptimization(100, 500, 90, 5, -2.0);
+    for (let i = 1; i < r.schedule.length; i++) {
+      expect(r.schedule[i].price).toBeLessThanOrEqual(r.schedule[i - 1].price);
+    }
+  });
+
+  it('expectedRevenue ≥ 0', () => {
+    const r = markdownOptimization(100, 500, 90, 5, -2.0);
+    expect(r.expectedRevenue).toBeGreaterThanOrEqual(0);
+  });
+
+  it('expectedUnsold ≥ 0', () => {
+    const r = markdownOptimization(100, 50, 30, 2, -3.0, [10]);
+    expect(r.expectedUnsold).toBeGreaterThanOrEqual(0);
+  });
+
+  it('throws for non-positive inventory', () => {
+    expect(() => markdownOptimization(100, 0, 90, 5, -2)).toThrow();
+  });
+});
+
+// ─── Customer Lifetime Value ──────────────────────────────────────────────────
+
+describe('customerLifetimeValue', () => {
+  /**
+   * AOV=$100, freq=4/yr, lifespan=5yr, r=0.10
+   * Simple CLV = 100 × 4 × 5 = $2000
+   * Discounted CLV = Σ_{t=1}^{5} 400 / 1.1^t ≈ 400 × 3.791 ≈ $1516
+   */
+  it('simpleCLV = AOV × frequency × lifespan', () => {
+    const r = customerLifetimeValue(100, 4, 5, 0.10);
+    expect(r.simpleCLV).toBeCloseTo(2000, 4);
+  });
+
+  it('discountedCLV < simpleCLV for positive discount rate', () => {
+    const r = customerLifetimeValue(100, 4, 5, 0.10);
+    expect(r.discountedCLV).toBeLessThan(r.simpleCLV);
+  });
+
+  it('discountedCLV ≈ simpleCLV when rate = 0', () => {
+    const r = customerLifetimeValue(100, 4, 5, 0);
+    expect(r.discountedCLV).toBeCloseTo(r.simpleCLV, 0);
+  });
+
+  it('CLV:CAC ratio computed when CAC provided', () => {
+    const r = customerLifetimeValue(100, 4, 5, 0.10, 200);
+    expect(r.clvToCac).not.toBeNull();
+    expect(r.clvToCac!).toBeCloseTo(r.discountedCLV / 200, 4);
+  });
+
+  it('CLV:CAC null when CAC not provided', () => {
+    const r = customerLifetimeValue(100, 4, 5, 0.10);
+    expect(r.clvToCac).toBeNull();
+  });
+
+  it('throws for zero AOV', () => {
+    expect(() => customerLifetimeValue(0, 4, 5, 0.10)).toThrow();
+  });
+});
+
+// ─── Conversion funnel ────────────────────────────────────────────────────────
+
+describe('conversionFunnelAnalysis', () => {
+  /**
+   * Funnel: Visit → Cart → Checkout → Purchase
+   * 10000 → 2000 → 500 → 250
+   * Step conversions: 20%, 25%, 50%
+   * Overall: 250/10000 = 2.5%
+   */
+  const stages = ['Visit', 'Cart', 'Checkout', 'Purchase'];
+  const counts = [10000, 2000, 500, 250];
+
+  it('step conversions correct', () => {
+    const r = conversionFunnelAnalysis(stages, counts, 75);
+    expect(r.stepConversions[0]).toBeCloseTo(0.20, 4);
+    expect(r.stepConversions[1]).toBeCloseTo(0.25, 4);
+    expect(r.stepConversions[2]).toBeCloseTo(0.50, 4);
+  });
+
+  it('overall conversion = final / first', () => {
+    const r = conversionFunnelAnalysis(stages, counts, 75);
+    expect(r.overallConversion).toBeCloseTo(0.025, 4);
+  });
+
+  it('sensitivity revenue is positive for each step', () => {
+    const r = conversionFunnelAnalysis(stages, counts, 75);
+    for (const s of r.sensitivityRevenue) expect(s).toBeGreaterThanOrEqual(0);
+  });
+
+  it('throws when stages.length ≠ counts.length', () => {
+    expect(() => conversionFunnelAnalysis(['A', 'B'], [100], 50)).toThrow();
+  });
+
+  it('throws for fewer than 2 stages', () => {
+    expect(() => conversionFunnelAnalysis(['A'], [100], 50)).toThrow();
+  });
+});
+
+// ─── ABC classification ───────────────────────────────────────────────────────
+
+describe('abcClassification', () => {
+  const items = [
+    { id: 'SKU-1', annualVolume: 100, unitCost: 500 },  // $50k — A
+    { id: 'SKU-2', annualVolume: 500, unitCost: 20  },  // $10k — A/B
+    { id: 'SKU-3', annualVolume: 1000, unitCost: 5  },  // $5k  — B
+    { id: 'SKU-4', annualVolume: 5000, unitCost: 0.5 }, // $2.5k — C
+    { id: 'SKU-5', annualVolume: 2000, unitCost: 0.2 }, // $400  — C
+  ];
+
+  it('class A item has highest annual value', () => {
+    const r = abcClassification(items);
+    expect(r.items[0].class).toBe('A');
+    expect(r.items[0].id).toBe('SKU-1');
+  });
+
+  it('all items are classified', () => {
+    const r = abcClassification(items);
+    expect(r.items).toHaveLength(items.length);
+  });
+
+  it('class A holds the largest share of total value (Pareto principle)', () => {
+    // With discrete items, class A may not hit exactly 80% — it holds up to 80% threshold
+    // SKU-1 ($50k) = 73.6% of total $67.9k — class A boundary stops adding items at 80%
+    const r = abcClassification(items);
+    expect(r.classValuePct.A).toBeGreaterThan(50);
+    expect(r.classValuePct.A + r.classValuePct.B + r.classValuePct.C).toBeCloseTo(100, 4);
+  });
+
+  it('cumulative % is monotonically increasing', () => {
+    const r = abcClassification(items);
+    for (let i = 1; i < r.items.length; i++) {
+      expect(r.items[i].cumulativePct).toBeGreaterThanOrEqual(r.items[i - 1].cumulativePct);
+    }
+  });
+
+  it('throws for empty items', () => {
+    expect(() => abcClassification([])).toThrow();
+  });
+});
+
+// ─── Inventory metrics ────────────────────────────────────────────────────────
+
+describe('inventoryMetrics', () => {
+  /**
+   * COGS=$500k, avg inventory=$100k → turnover=5, DSI=73 days
+   */
+  it('inventory turnover = COGS / avgInventory', () => {
+    const r = inventoryMetrics(500_000, 100_000);
+    expect(r.inventoryTurnover).toBeCloseTo(5, 5);
+  });
+
+  it('DSI = 365 / turnover', () => {
+    const r = inventoryMetrics(500_000, 100_000);
+    expect(r.dsi).toBeCloseTo(365 / 5, 4);
+  });
+
+  it('withinTarget=true when DSI ≤ targetDsi', () => {
+    const r = inventoryMetrics(500_000, 100_000, 90);
+    expect(r.withinTarget).toBe(true);
+  });
+
+  it('withinTarget=false when DSI > targetDsi', () => {
+    const r = inventoryMetrics(100_000, 100_000, 30); // DSI=365 > 30
+    expect(r.withinTarget).toBe(false);
+  });
+
+  it('throws for zero COGS', () => {
+    expect(() => inventoryMetrics(0, 100_000)).toThrow();
+  });
+});
+
+// ─── Receipt ─────────────────────────────────────────────────────────────────
+
+describe('buildRetailReceipt', () => {
+  it('produces receipt with plugin=retail-ecommerce and CAEL event', () => {
+    const eoq = economicOrderQuantity(1000, 10, 2.5);
+    const receipt = buildRetailReceipt({ eoq, converged: true });
+    expect(receipt.plugin).toBe('retail-ecommerce');
+    expect(receipt.cael.event).toBe('retail_ecommerce.retail_analysis');
+    expect(receipt.payloadHash).toBeTruthy();
+  });
+
+  it('accepted=true for healthy metrics', () => {
+    const clv = customerLifetimeValue(200, 5, 3, 0.10, 150); // CLV:CAC ≈ 3+
+    const receipt = buildRetailReceipt({ clv, converged: true });
+    expect(receipt.acceptance.accepted).toBe(true);
+  });
+
+  it('accepted=false when CLV:CAC < 3', () => {
+    const clv = customerLifetimeValue(50, 1, 1, 0.10, 500); // poor CLV:CAC
+    const receipt = buildRetailReceipt({ clv, converged: true });
+    if (clv.clvToCac! < 3) {
+      expect(receipt.acceptance.accepted).toBe(false);
+      expect(receipt.acceptance.violations.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('uses provided runId', () => {
+    const receipt = buildRetailReceipt({ converged: true }, { runId: 'retail-run-42' });
+    expect(receipt.runId).toBe('retail-run-42');
+  });
+});

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

@@ -0,0 +1,108 @@
+/**
+ * Integration proof: the retail-ecommerce `eoq` trait, once registered via the
+ * runtime's real `registerTrait` seam, is dispatched BY THE RUNTIME and runs
+ * the Harris-Wilson Economic Order Quantity solver — NOT called directly as a
+ * handler object (the thin convention every other trait test uses).
+ *
+ * Mirrors the energy-grid reference integration. Drives the real path:
+ * executeNode(orb) -> orb-executor -> applyDirectives ->
+ * traitHandlers.get('eoq').onAttach -> economicOrderQuantity.
+ * 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 { registerRetailEcommerceTraitHandlers } from '../runtime';
+
+// Hand-checkable EOQ: D=1000, S=10, H=2.5 => sqrt(2*1000*10/2.5) = sqrt(8000) ≈ 89.4427.
+const EOQ_CONFIG = {
+  annualDemand: 1000,
+  orderingCost: 10,
+  holdingCostPerUnit: 2.5,
+};
+const EXPECTED_EOQ = Math.sqrt((2 * 1000 * 10) / 2.5); // 89.44271909999159
+
+function eoqOrb(config: Record<string, unknown>): unknown {
+  return {
+    type: 'orb',
+    name: 'retail',
+    properties: {},
+    methods: [],
+    position: [0, 0, 0],
+    hologram: { shape: 'orb', color: '#fff', size: 1, glow: false, interactive: false },
+    directives: [{ type: 'trait', name: 'eoq', config }],
+  };
+}
+
+/** Flush the runtime's async emit dispatch so `on` listeners have fired. */
+const flush = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0));
+
+describe('retail-ecommerce -> HoloScript runtime integration (eoq)', () => {
+  it('runtime dispatch runs the EOQ solver for a registered @eoq orb', async () => {
+    const runtime = new HoloScriptRuntime();
+    registerRetailEcommerceTraitHandlers(runtime);
+
+    const solved: Array<Record<string, unknown>> = [];
+    runtime.on('eoq_solved', (e: unknown) => {
+      solved.push(e as Record<string, unknown>);
+    });
+
+    await runtime.executeNode(eoqOrb(EOQ_CONFIG) as never);
+    await flush();
+
+    expect(solved).toHaveLength(1);
+    const summary = solved[0];
+    // EOQ = sqrt(2*D*S/H) = sqrt(8000) ≈ 89.44.
+    expect(summary.eoq as number).toBeCloseTo(EXPECTED_EOQ, 5);
+    expect(summary.eoq as number).toBeCloseTo(89.4427, 4);
+    // ordersPerYear = D / EOQ = 1000 / 89.4427 ≈ 11.1803.
+    expect(summary.ordersPerYear as number).toBeCloseTo(1000 / EXPECTED_EOQ, 5);
+    expect(summary.annualDemand).toBe(1000);
+  });
+
+  it('NEGATIVE CONTROL: without registration the @eoq trait is a dead no-op', async () => {
+    const runtime = new HoloScriptRuntime(); // intentionally NOT registered
+    const solved: unknown[] = [];
+    runtime.on('eoq_solved', (e: unknown) => solved.push(e));
+
+    await runtime.executeNode(eoqOrb(EOQ_CONFIG) as never);
+    await flush();
+
+    expect(solved).toHaveLength(0);
+  });
+
+  it('persists the solver result into durable runtime state on ATTACH', async () => {
+    const runtime = new HoloScriptRuntime();
+    registerRetailEcommerceTraitHandlers(runtime);
+
+    await runtime.executeNode(eoqOrb(EOQ_CONFIG) as never);
+    await flush();
+
+    const state = runtime.getState() as Record<string, unknown>;
+    const persisted = state['eoq:retail'] as
+      | { eoq?: number; annualDemand?: number }
+      | undefined;
+    expect(persisted).toBeDefined();
+    expect(persisted?.eoq).toBeCloseTo(EXPECTED_EOQ, 5);
+    expect(persisted?.annualDemand).toBe(1000);
+  });
+
+  it('emits eoq_error (does not throw through the runtime) for missing inputs', async () => {
+    const runtime = new HoloScriptRuntime();
+    registerRetailEcommerceTraitHandlers(runtime);
+
+    const errors: Array<Record<string, unknown>> = [];
+    runtime.on('eoq_error', (e: unknown) => {
+      errors.push(e as Record<string, unknown>);
+    });
+
+    // holdingCostPerUnit omitted -> the handler emits eoq_error, never throws.
+    await runtime.executeNode(
+      eoqOrb({ annualDemand: 1000, orderingCost: 10 }) as never,
+    );
+    await flush();
+
+    expect(errors).toHaveLength(1);
+    expect(String(errors[0].error)).toContain('holdingCostPerUnit');
+  });
+});

package/src/index.ts

@@ -0,0 +1,18 @@
+export { createCartHandler, type CartConfig, type CartItem, type CartState } from './traits/CartTrait';
+export { createCheckoutHandler, type CheckoutConfig, type CheckoutStep, type PaymentMethod, type Address } from './traits/CheckoutTrait';
+export { createProductCatalogHandler, type ProductCatalogConfig, type Product } from './traits/ProductCatalogTrait';
+export { createShippingRateHandler, type ShippingRateConfig, type ShippingMethod } from './traits/ShippingRateTrait';
+export { createReturnHandler, type ReturnConfig, type ReturnStatus } from './traits/ReturnTrait';
+export * from './traits/types';
+
+import { createCartHandler } from './traits/CartTrait';
+import { createCheckoutHandler } from './traits/CheckoutTrait';
+import { createProductCatalogHandler } from './traits/ProductCatalogTrait';
+import { createShippingRateHandler } from './traits/ShippingRateTrait';
+import { createReturnHandler } from './traits/ReturnTrait';
+
+export * from './retailsolver';
+export * from './runtime';
+
+export const pluginMeta = { name: '@holoscript/plugin-retail-ecommerce', version: '1.0.0', traits: ['cart', 'checkout', 'product_catalog', 'shipping_rate', 'return', 'eoq', 'price_optimization', 'markdown', 'clv', 'conversion_funnel', 'abc_classification', 'inventory_metrics'] };
+export const traitHandlers = [createCartHandler(), createCheckoutHandler(), createProductCatalogHandler(), createShippingRateHandler(), createReturnHandler()];

package/src/retailsolver.ts

@@ -0,0 +1,446 @@
+/**
+ * Retail & e-commerce solvers — retail-ecommerce-plugin
+ *
+ * Implements:
+ *  - EOQ (Economic Order Quantity) inventory optimization
+ *  - Demand elasticity and price optimization
+ *  - Markdown optimization (progressive discounting)
+ *  - Customer Lifetime Value (CLV) estimation
+ *  - Conversion funnel analysis
+ *  - ABC inventory classification
+ *  - Days sales of inventory (DSI) and inventory turnover
+ *
+ * References:
+ *  - Harris FW (1913) Operations and Cost — original EOQ paper
+ *  - Philips RL (2005) Pricing and Revenue Optimization — demand elasticity
+ *  - Fader PS et al. (2005) J.Marketing Res. — Pareto/NBD CLV model
+ */
+
+import { buildDomainSimulationReceipt, type DomainSimulationReceipt } from '@holoscript/core';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface EOQResult {
+  /** Annual demand units */
+  annualDemand: number;
+  /** Ordering cost per order ($) */
+  orderingCost: number;
+  /** Holding cost per unit per year ($) */
+  holdingCostPerUnit: number;
+  /** Optimal order quantity units */
+  eoq: number;
+  /** Number of orders per year */
+  ordersPerYear: number;
+  /** Total annual inventory cost ($) */
+  totalAnnualCost: number;
+  /** Reorder point given lead time demand */
+  reorderPoint: number;
+}
+
+export interface PriceOptimizationResult {
+  /** Current price */
+  currentPrice: number;
+  /** Price elasticity of demand (negative) */
+  elasticity: number;
+  /** Profit-maximizing price */
+  optimalPrice: number;
+  /** Revenue at current price */
+  currentRevenue: number;
+  /** Revenue at optimal price */
+  optimalRevenue: number;
+  /** Revenue uplift % */
+  revenueUpliftPct: number;
+  /** Price-demand curve points */
+  priceDemandCurve: Array<{ price: number; demand: number; revenue: number }>;
+}
+
+export interface MarkdownResult {
+  /** Original price */
+  originalPrice: number;
+  /** Remaining inventory units */
+  inventory: number;
+  /** Days until season end */
+  daysRemaining: number;
+  /** Optimal markdown schedule */
+  schedule: Array<{ dayOfMarkdown: number; discountPct: number; price: number; expectedUnits: number }>;
+  /** Expected total revenue */
+  expectedRevenue: number;
+  /** Expected unsold units */
+  expectedUnsold: number;
+}
+
+export interface CLVResult {
+  /** Average purchase value */
+  avgOrderValue: number;
+  /** Purchase frequency per year */
+  purchaseFrequency: number;
+  /** Customer lifespan years */
+  lifespanYears: number;
+  /** Discount rate */
+  discountRate: number;
+  /** Simple CLV = AOV × frequency × lifespan */
+  simpleCLV: number;
+  /** Discounted CLV (NPV of future purchases) */
+  discountedCLV: number;
+  /** CLV-to-CAC ratio (if CAC provided) */
+  clvToCac: number | null;
+}
+
+export interface FunnelAnalysisResult {
+  stages: string[];
+  counts: number[];
+  /** Conversion rate stage-to-stage */
+  stepConversions: number[];
+  /** Overall funnel conversion rate */
+  overallConversion: number;
+  /** Revenue impact of improving each step by 10pp */
+  sensitivityRevenue: number[];
+}
+
+export interface ABCClassification {
+  items: Array<{
+    id: string;
+    annualValue: number;
+    cumulativePct: number;
+    class: 'A' | 'B' | 'C';
+  }>;
+  /** Count of A, B, C items */
+  classCounts: { A: number; B: number; C: number };
+  /** % of total value in each class */
+  classValuePct: { A: number; B: number; C: number };
+}
+
+export interface RetailReceiptOptions {
+  runId?: string;
+}
+
+// ─── EOQ ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Classic Economic Order Quantity (Harris-Wilson formula).
+ * EOQ = √(2 × D × S / H)
+ * where D = annual demand, S = ordering cost, H = holding cost per unit/year.
+ */
+export function economicOrderQuantity(
+  annualDemand: number,
+  orderingCost: number,
+  holdingCostPerUnit: number,
+  leadTimeDays = 0,
+  workingDaysPerYear = 250,
+): EOQResult {
+  if (annualDemand <= 0) throw new Error('annualDemand must be positive');
+  if (orderingCost <= 0) throw new Error('orderingCost must be positive');
+  if (holdingCostPerUnit <= 0) throw new Error('holdingCostPerUnit must be positive');
+
+  const eoq = Math.sqrt((2 * annualDemand * orderingCost) / holdingCostPerUnit);
+  const ordersPerYear = annualDemand / eoq;
+  const totalAnnualCost = (annualDemand / eoq) * orderingCost + (eoq / 2) * holdingCostPerUnit;
+  const dailyDemand = annualDemand / workingDaysPerYear;
+  const reorderPoint = dailyDemand * leadTimeDays;
+
+  return { annualDemand, orderingCost, holdingCostPerUnit, eoq, ordersPerYear, totalAnnualCost, reorderPoint };
+}
+
+// ─── Price optimization via demand elasticity ─────────────────────────────────
+
+/**
+ * Optimize price using constant-elasticity demand model.
+ * Q(P) = Q₀ × (P/P₀)^ε   where ε < 0 (price elasticity)
+ *
+ * Revenue R(P) = P × Q(P)
+ * Optimal (revenue-maximizing) price: P* = P₀ / (1 + 1/ε)  [markup formula]
+ * For elastic demand (ε < -1): P* < P₀ (lower price increases revenue)
+ * For inelastic demand (-1 < ε < 0): P* > P₀
+ *
+ * Variable cost per unit optional for profit maximization.
+ */
+export function priceOptimization(
+  currentPrice: number,
+  currentDemand: number,
+  elasticity: number,
+  variableCost = 0,
+  priceRange?: [number, number],
+): PriceOptimizationResult {
+  if (currentPrice <= 0) throw new Error('currentPrice must be positive');
+  if (currentDemand <= 0) throw new Error('currentDemand must be positive');
+  if (elasticity >= 0) throw new Error('elasticity must be negative (price-demand law)');
+
+  const demandAt = (p: number) => currentDemand * Math.pow(p / currentPrice, elasticity);
+  const revenueAt = (p: number) => p * demandAt(p);
+  const profitAt  = (p: number) => (p - variableCost) * demandAt(p);
+
+  // Profit-maximizing price via ternary search
+  const pLo = priceRange ? priceRange[0] : variableCost * 1.01;
+  const pHi = priceRange ? priceRange[1] : currentPrice * 3;
+
+  let lo = Math.max(pLo, variableCost + 0.01), hi = pHi;
+  for (let i = 0; i < 100; i++) {
+    const m1 = lo + (hi - lo) / 3;
+    const m2 = hi - (hi - lo) / 3;
+    if (profitAt(m1) < profitAt(m2)) lo = m1; else hi = m2;
+  }
+  const optimalPrice = (lo + hi) / 2;
+
+  const currentRevenue  = revenueAt(currentPrice);
+  const optimalRevenue  = revenueAt(optimalPrice);
+  const revenueUpliftPct = ((optimalRevenue - currentRevenue) / currentRevenue) * 100;
+
+  // Price-demand curve: 20 points from 50% to 200% of current price
+  const priceDemandCurve = Array.from({ length: 21 }, (_, i) => {
+    const p = currentPrice * (0.5 + i * 0.075);
+    return { price: p, demand: demandAt(p), revenue: revenueAt(p) };
+  });
+
+  return { currentPrice, elasticity, optimalPrice, currentRevenue, optimalRevenue, revenueUpliftPct, priceDemandCurve };
+}
+
+// ─── Markdown optimization ────────────────────────────────────────────────────
+
+/**
+ * Progressive markdown optimization using a greedy sell-through target approach.
+ * Demand increases with discount depth per price elasticity.
+ */
+export function markdownOptimization(
+  originalPrice: number,
+  inventory: number,
+  daysRemaining: number,
+  baseDailySalesRate: number,
+  elasticity: number,
+  markdownSteps: number[] = [10, 20, 30, 50],
+): MarkdownResult {
+  if (originalPrice <= 0) throw new Error('originalPrice must be positive');
+  if (inventory <= 0) throw new Error('inventory must be positive');
+  if (daysRemaining < 1) throw new Error('daysRemaining must be ≥ 1');
+  if (elasticity >= 0) throw new Error('elasticity must be negative');
+
+  // Simple greedy: evenly space markdowns across remaining days
+  const stepSize = Math.floor(daysRemaining / (markdownSteps.length + 1));
+  let remaining = inventory;
+  let totalRevenue = 0;
+
+  const schedule: MarkdownResult['schedule'] = [];
+  let currentPrice = originalPrice;
+  let currentRate = baseDailySalesRate;
+  let prevDay = 0;
+
+  for (let si = 0; si < markdownSteps.length; si++) {
+    const dayOfMarkdown = (si + 1) * stepSize;
+    const discountPct = markdownSteps[si];
+    const newPrice = originalPrice * (1 - discountPct / 100);
+    // Demand boost from discount via elasticity
+    const newRate = baseDailySalesRate * Math.pow(1 - discountPct / 100, elasticity);
+
+    // Sell from prevDay to dayOfMarkdown at currentRate/price
+    const daysAtCurrentPrice = dayOfMarkdown - prevDay;
+    const unitsSold = Math.min(remaining, Math.round(currentRate * daysAtCurrentPrice));
+    totalRevenue += unitsSold * currentPrice;
+    remaining = Math.max(0, remaining - unitsSold);
+
+    schedule.push({ dayOfMarkdown, discountPct, price: newPrice, expectedUnits: Math.round(newRate * stepSize) });
+
+    currentPrice = newPrice;
+    currentRate = newRate;
+    prevDay = dayOfMarkdown;
+  }
+
+  // Final period after last markdown
+  const finalDays = daysRemaining - prevDay;
+  const finalUnits = Math.min(remaining, Math.round(currentRate * finalDays));
+  totalRevenue += finalUnits * currentPrice;
+  remaining = Math.max(0, remaining - finalUnits);
+
+  return { originalPrice, inventory, daysRemaining, schedule, expectedRevenue: totalRevenue, expectedUnsold: remaining };
+}
+
+// ─── Customer Lifetime Value ──────────────────────────────────────────────────
+
+/**
+ * Compute CLV using simple and discounted (NPV) formulas.
+ * Simple: CLV = AOV × frequency × lifespan
+ * Discounted: CLV = Σ_{t=1}^{L} AOV × freq / (1+r)^t
+ */
+export function customerLifetimeValue(
+  avgOrderValue: number,
+  purchaseFrequency: number,
+  lifespanYears: number,
+  discountRate: number,
+  cac?: number,
+): CLVResult {
+  if (avgOrderValue <= 0) throw new Error('avgOrderValue must be positive');
+  if (purchaseFrequency <= 0) throw new Error('purchaseFrequency must be positive');
+  if (lifespanYears <= 0) throw new Error('lifespanYears must be positive');
+  if (discountRate < 0) throw new Error('discountRate must be non-negative');
+
+  const simpleCLV = avgOrderValue * purchaseFrequency * lifespanYears;
+
+  // Discounted: annual revenue / (1+r)^year, summed
+  let discountedCLV = 0;
+  const annualRevenue = avgOrderValue * purchaseFrequency;
+  for (let y = 1; y <= Math.ceil(lifespanYears); y++) {
+    const weight = Math.min(1, lifespanYears - (y - 1)); // partial last year
+    discountedCLV += (weight * annualRevenue) / Math.pow(1 + discountRate, y);
+  }
+
+  const clvToCac = cac != null && cac > 0 ? discountedCLV / cac : null;
+
+  return { avgOrderValue, purchaseFrequency, lifespanYears, discountRate, simpleCLV, discountedCLV, clvToCac };
+}
+
+// ─── Conversion funnel analysis ───────────────────────────────────────────────
+
+/**
+ * Analyze a conversion funnel and compute revenue sensitivity.
+ */
+export function conversionFunnelAnalysis(
+  stages: string[],
+  counts: number[],
+  avgOrderValue: number,
+): FunnelAnalysisResult {
+  if (stages.length !== counts.length) throw new Error('stages and counts must have same length');
+  if (stages.length < 2) throw new Error('Funnel needs at least 2 stages');
+  if (counts.some(c => c < 0)) throw new Error('counts must be non-negative');
+  if (avgOrderValue <= 0) throw new Error('avgOrderValue must be positive');
+
+  const stepConversions = counts.slice(1).map((c, i) => counts[i] > 0 ? c / counts[i] : 0);
+  const overallConversion = counts[0] > 0 ? counts[counts.length - 1] / counts[0] : 0;
+  const currentRevenue = counts[counts.length - 1] * avgOrderValue;
+
+  // Sensitivity: if step i conversion improves by 10pp, how much extra revenue?
+  const sensitivityRevenue = stepConversions.map((conv, i) => {
+    const newConv = Math.min(1, conv + 0.10);
+    const upliftFactor = newConv / (conv || 1e-9);
+    // Downstream: all subsequent stages are multiplied by this factor
+    let newFinal = counts[i + 1] * upliftFactor;
+    for (let j = i + 2; j < counts.length; j++) {
+      newFinal *= (counts[j - 1] > 0 ? counts[j] / counts[j - 1] : 1);
+    }
+    return (newFinal - counts[counts.length - 1]) * avgOrderValue;
+  });
+
+  return { stages, counts, stepConversions, overallConversion, sensitivityRevenue };
+}
+
+// ─── ABC inventory classification ─────────────────────────────────────────────
+
+/**
+ * Classify inventory items into A/B/C tiers by annual value contribution.
+ * A: top 80% of value (~20% of items)
+ * B: next 15% of value
+ * C: remaining 5% of value
+ */
+export function abcClassification(
+  items: Array<{ id: string; annualVolume: number; unitCost: number }>,
+): ABCClassification {
+  if (items.length === 0) throw new Error('No items provided');
+
+  const withValues = items.map(item => ({
+    id: item.id,
+    annualValue: item.annualVolume * item.unitCost,
+  })).sort((a, b) => b.annualValue - a.annualValue);
+
+  const totalValue = withValues.reduce((a, b) => a + b.annualValue, 0);
+  let cumulative = 0;
+  const classCounts = { A: 0, B: 0, C: 0 };
+  const classValue  = { A: 0, B: 0, C: 0 };
+
+  const classified = withValues.map(item => {
+    cumulative += item.annualValue;
+    const cumulativePct = (cumulative / totalValue) * 100;
+    const cls: 'A' | 'B' | 'C' = cumulativePct <= 80 ? 'A' : cumulativePct <= 95 ? 'B' : 'C';
+    classCounts[cls]++;
+    classValue[cls] += item.annualValue;
+    return { ...item, cumulativePct, class: cls };
+  });
+
+  const classValuePct = {
+    A: (classValue.A / totalValue) * 100,
+    B: (classValue.B / totalValue) * 100,
+    C: (classValue.C / totalValue) * 100,
+  };
+
+  return { items: classified, classCounts, classValuePct };
+}
+
+// ─── Inventory turnover & DSI ─────────────────────────────────────────────────
+
+export interface InventoryMetrics {
+  /** Cost of goods sold */
+  cogs: number;
+  /** Average inventory value */
+  avgInventory: number;
+  /** Inventory turnover ratio = COGS / avg inventory */
+  inventoryTurnover: number;
+  /** Days sales of inventory = 365 / turnover */
+  dsi: number;
+  /** Target DSI (if provided) */
+  targetDsi?: number;
+  /** Whether current DSI is within target */
+  withinTarget?: boolean;
+}
+
+export function inventoryMetrics(
+  cogs: number,
+  avgInventory: number,
+  targetDsi?: number,
+): InventoryMetrics {
+  if (cogs <= 0) throw new Error('COGS must be positive');
+  if (avgInventory <= 0) throw new Error('avgInventory must be positive');
+
+  const inventoryTurnover = cogs / avgInventory;
+  const dsi = 365 / inventoryTurnover;
+
+  return {
+    cogs, avgInventory, inventoryTurnover, dsi,
+    targetDsi,
+    withinTarget: targetDsi != null ? dsi <= targetDsi : undefined,
+  };
+}
+
+// ─── Receipt ──────────────────────────────────────────────────────────────────
+
+export interface RetailAnalysisResult {
+  eoq?: EOQResult;
+  priceOpt?: PriceOptimizationResult;
+  markdown?: MarkdownResult;
+  clv?: CLVResult;
+  funnel?: FunnelAnalysisResult;
+  abc?: ABCClassification;
+  inventory?: InventoryMetrics;
+  converged: true;
+}
+
+export function buildRetailReceipt(
+  result: RetailAnalysisResult,
+  options?: RetailReceiptOptions,
+): DomainSimulationReceipt {
+  const violations: Array<{ criterion: string; message: string }> = [];
+
+  if (result.inventory?.withinTarget === false) {
+    violations.push({
+      criterion: 'dsi',
+      message: `DSI ${result.inventory.dsi.toFixed(1)} days exceeds target ${result.inventory.targetDsi} days`,
+    });
+  }
+  if (result.clv?.clvToCac != null && result.clv.clvToCac < 3) {
+    violations.push({
+      criterion: 'clv_to_cac',
+      message: `CLV:CAC ratio ${result.clv.clvToCac.toFixed(2)} is below recommended minimum of 3`,
+    });
+  }
+
+  return buildDomainSimulationReceipt({
+    plugin: 'retail-ecommerce',
+    pluginVersion: '1.0.0',
+    runId: options?.runId ?? `retail-${Date.now().toString(36)}`,
+    solverConfig: { solverType: 'retail-analytics', scale: 'store' },
+    resultSummary: {
+      eoq: result.eoq?.eoq ?? null,
+      optimalPrice: result.priceOpt?.optimalPrice ?? null,
+      revenueUpliftPct: result.priceOpt?.revenueUpliftPct ?? null,
+      clv: result.clv?.discountedCLV ?? null,
+      overallConversion: result.funnel?.overallConversion ?? null,
+    },
+    cael: { version: 'cael.v1', event: 'retail_ecommerce.retail_analysis', solverType: 'retail-ecommerce.analytics' },
+    acceptance: { accepted: violations.length === 0, violations },
+  });
+}

package/src/runtime.ts

@@ -0,0 +1,162 @@
+/**
+ * Runtime integration for @holoscript/plugin-retail-ecommerce.
+ *
+ * Bridges the previously dead-wired `eoq` trait into a behavioral
+ * TraitHandler that the HoloScript runtime actually dispatches
+ * (HoloScriptRuntime.registerTrait -> applyDirectives / updateTraits).
+ *
+ * Before this module the plugin declared trait NAMES only
+ * (pluginMeta.traits) and exported `economicOrderQuantity` plus the other
+ * retail solvers, but nothing invoked a solver THROUGH the runtime — the whole
+ * domain-plugin tier was built-but-dead-wired. This mirrors the energy-grid
+ * reference integration (`power_flow` -> `solveDCPowerFlow`): the `eoq` trait
+ * now runs the real Harris-Wilson Economic Order Quantity solver via the
+ * shared `registerPluginTraits` registrar. The remaining declared trait names
+ * follow the same registrar shape.
+ */
+import { registerPluginTraits } from '@holoscript/core/runtime';
+import { economicOrderQuantity, type EOQResult } from './retailsolver';
+
+/** Stable id for this plugin, used by the runtime collision guard. */
+export const RETAIL_ECOMMERCE_PLUGIN_ID = 'retail-ecommerce' as const;
+
+/** Config carried by an orb's `@eoq` trait directive. */
+export interface EoqTraitConfig {
+  /** Annual demand units. Required; absence emits `eoq_error`. */
+  annualDemand?: number;
+  /** Ordering cost per order ($). Required; absence emits `eoq_error`. */
+  orderingCost?: number;
+  /** Holding cost per unit per year ($). Required; absence emits `eoq_error`. */
+  holdingCostPerUnit?: number;
+  /** Optional lead time (days) used to compute the reorder point. */
+  leadTimeDays?: number;
+  /** Optional working days per year forwarded to `economicOrderQuantity`. */
+  workingDaysPerYear?: number;
+}
+
+/** Summary payload emitted on `eoq_solved`. */
+export interface EoqSolvedEvent {
+  nodeId: string;
+  eoq: number;
+  ordersPerYear: number;
+  totalAnnualCost: number;
+  reorderPoint: number;
+  annualDemand: 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: EoqTraitConfig, context: TraitDispatchContext) => void;
+  onUpdate?: (
+    node: unknown,
+    config: EoqTraitConfig,
+    context: TraitDispatchContext,
+    delta: number,
+  ) => void;
+}
+
+interface EoqNode {
+  id?: string;
+  name?: string;
+  properties?: Record<string, unknown>;
+  __eoqResult?: EOQResult;
+}
+
+/** Solve EOQ from `config`, write the result onto the node, and emit. */
+function solveOntoNode(
+  node: unknown,
+  config: EoqTraitConfig | undefined,
+  context: TraitDispatchContext,
+): void {
+  const carrier = node as EoqNode;
+  const nodeId = carrier.id ?? carrier.name ?? 'unknown';
+
+  const annualDemand = config?.annualDemand;
+  const orderingCost = config?.orderingCost;
+  const holdingCostPerUnit = config?.holdingCostPerUnit;
+
+  if (
+    annualDemand === undefined ||
+    orderingCost === undefined ||
+    holdingCostPerUnit === undefined
+  ) {
+    context.emit('eoq_error', {
+      nodeId,
+      error:
+        'eoq trait requires config.annualDemand, config.orderingCost, and config.holdingCostPerUnit',
+    });
+    return;
+  }
+
+  try {
+    const result = economicOrderQuantity(
+      annualDemand,
+      orderingCost,
+      holdingCostPerUnit,
+      config?.leadTimeDays ?? 0,
+      config?.workingDaysPerYear ?? 250,
+    );
+    carrier.__eoqResult = result;
+    carrier.properties = {
+      ...(carrier.properties ?? {}),
+      eoq: result.eoq,
+      ordersPerYear: result.ordersPerYear,
+      totalAnnualCost: result.totalAnnualCost,
+    };
+    const summary: EoqSolvedEvent = {
+      nodeId,
+      eoq: result.eoq,
+      ordersPerYear: result.ordersPerYear,
+      totalAnnualCost: result.totalAnnualCost,
+      reorderPoint: result.reorderPoint,
+      annualDemand: result.annualDemand,
+    };
+    context.setState?.({ [`eoq:${nodeId}`]: summary });
+    context.emit('eoq_solved', summary);
+  } catch (error) {
+    context.emit('eoq_error', {
+      nodeId,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+/**
+ * Behavioral handler for the retail-ecommerce `eoq` trait. Runs the
+ * deterministic Harris-Wilson Economic Order Quantity solver whenever an orb
+ * carrying the trait is attached (and on each per-frame update), writing the
+ * result onto the node and emitting `eoq_solved` / `eoq_error`.
+ */
+export const eoqHandler: RuntimeTraitHandler = {
+  name: 'eoq',
+  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 retail-ecommerce 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 retail EOQ solver for `@eoq` orbs.
+ */
+export function registerRetailEcommerceTraitHandlers(registrar: TraitRegistrar): void {
+  registerPluginTraits(registrar, RETAIL_ECOMMERCE_PLUGIN_ID, [eoqHandler]);
+}

package/src/traits/CartTrait.ts

@@ -0,0 +1,42 @@
+/** @cart Trait — Shopping cart management. @trait cart */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export interface CartItem { productId: string; quantity: number; price: number; variant?: string; name: string; }
+export interface CartConfig { currency: string; items: CartItem[]; maxItems: number; taxRate: number; }
+export interface CartState { items: CartItem[]; subtotal: number; tax: number; total: number; itemCount: number; }
+
+const defaultConfig: CartConfig = { currency: 'USD', items: [], maxItems: 99, taxRate: 0 };
+
+function computeTotals(items: CartItem[], taxRate: number): Pick<CartState, 'subtotal' | 'tax' | 'total' | 'itemCount'> {
+  const subtotal = items.reduce((sum, i) => sum + i.price * i.quantity, 0);
+  const tax = subtotal * taxRate;
+  return { subtotal, tax, total: subtotal + tax, itemCount: items.reduce((sum, i) => sum + i.quantity, 0) };
+}
+
+export function createCartHandler(): TraitHandler<CartConfig> {
+  return {
+    name: 'cart', defaultConfig,
+    onAttach(node: HSPlusNode, config: CartConfig, ctx: TraitContext) {
+      const totals = computeTotals(config.items, config.taxRate);
+      node.__cartState = { items: [...config.items], ...totals };
+      ctx.emit?.('cart:created', { itemCount: totals.itemCount });
+    },
+    onDetach(node: HSPlusNode, _c: CartConfig, ctx: TraitContext) { delete node.__cartState; ctx.emit?.('cart:cleared'); },
+    onUpdate() {},
+    onEvent(node: HSPlusNode, config: CartConfig, ctx: TraitContext, event: TraitEvent) {
+      const s = node.__cartState as CartState | undefined; if (!s) return;
+      if (event.type === 'cart:add_item') {
+        const item = event.payload as unknown as CartItem;
+        const existing = s.items.find(i => i.productId === item.productId && i.variant === item.variant);
+        if (existing) existing.quantity += item.quantity; else s.items.push({ ...item });
+        Object.assign(s, computeTotals(s.items, config.taxRate));
+        ctx.emit?.('cart:updated', { itemCount: s.itemCount, total: s.total });
+      }
+      if (event.type === 'cart:remove_item') {
+        s.items = s.items.filter(i => i.productId !== (event.payload?.productId as string));
+        Object.assign(s, computeTotals(s.items, config.taxRate));
+        ctx.emit?.('cart:updated', { itemCount: s.itemCount, total: s.total });
+      }
+    },
+  };
+}

package/src/traits/CheckoutTrait.ts

@@ -0,0 +1,29 @@
+/** @checkout Trait — Checkout flow management. @trait checkout */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type CheckoutStep = 'shipping' | 'payment' | 'review' | 'confirm' | 'complete';
+export type PaymentMethod = 'credit_card' | 'debit_card' | 'paypal' | 'crypto' | 'bank_transfer' | 'apple_pay';
+export interface Address { line1: string; line2?: string; city: string; state: string; postalCode: string; country: string; }
+export interface CheckoutConfig { step: CheckoutStep; paymentMethod: PaymentMethod; shippingAddress: Address | null; billingAddress: Address | null; orderTotal: number; tax: number; }
+export interface CheckoutState { currentStep: CheckoutStep; isProcessing: boolean; orderId: string | null; error: string | null; }
+
+const defaultConfig: CheckoutConfig = { step: 'shipping', paymentMethod: 'credit_card', shippingAddress: null, billingAddress: null, orderTotal: 0, tax: 0 };
+
+export function createCheckoutHandler(): TraitHandler<CheckoutConfig> {
+  return {
+    name: 'checkout', defaultConfig,
+    onAttach(node: HSPlusNode, config: CheckoutConfig, ctx: TraitContext) { node.__checkoutState = { currentStep: config.step, isProcessing: false, orderId: null, error: null }; ctx.emit?.('checkout:started'); },
+    onDetach(node: HSPlusNode, _c: CheckoutConfig, ctx: TraitContext) { delete node.__checkoutState; ctx.emit?.('checkout:abandoned'); },
+    onUpdate() {},
+    onEvent(node: HSPlusNode, _c: CheckoutConfig, ctx: TraitContext, event: TraitEvent) {
+      const s = node.__checkoutState as CheckoutState | undefined; if (!s) return;
+      if (event.type === 'checkout:next_step') {
+        const steps: CheckoutStep[] = ['shipping', 'payment', 'review', 'confirm', 'complete'];
+        const idx = steps.indexOf(s.currentStep);
+        if (idx < steps.length - 1) { s.currentStep = steps[idx + 1]; ctx.emit?.('checkout:step_changed', { step: s.currentStep }); }
+      }
+      if (event.type === 'checkout:process_payment') { s.isProcessing = true; ctx.emit?.('checkout:processing'); }
+      if (event.type === 'checkout:complete') { s.currentStep = 'complete'; s.orderId = event.payload?.orderId as string; ctx.emit?.('checkout:completed', { orderId: s.orderId }); }
+    },
+  };
+}

package/src/traits/ProductCatalogTrait.ts

@@ -0,0 +1,28 @@
+/** @product_catalog Trait — Product catalog with search and filtering. @trait product_catalog */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export interface Product { id: string; name: string; price: number; category: string; brand?: string; inStock: boolean; imageUrl?: string; }
+export interface ProductCatalogConfig { products: Product[]; categories: string[]; sortBy: 'price_asc' | 'price_desc' | 'name' | 'newest'; pageSize: number; }
+
+const defaultConfig: ProductCatalogConfig = { products: [], categories: [], sortBy: 'name', pageSize: 20 };
+
+export function createProductCatalogHandler(): TraitHandler<ProductCatalogConfig> {
+  return {
+    name: 'product_catalog', defaultConfig,
+    onAttach(node: HSPlusNode, config: ProductCatalogConfig, ctx: TraitContext) { node.__catalogState = { currentPage: 0, filteredCount: config.products.length, activeFilters: {} }; ctx.emit?.('catalog:loaded', { productCount: config.products.length }); },
+    onDetach(node: HSPlusNode, _c: ProductCatalogConfig, ctx: TraitContext) { delete node.__catalogState; ctx.emit?.('catalog:unloaded'); },
+    onUpdate() {},
+    onEvent(node: HSPlusNode, config: ProductCatalogConfig, ctx: TraitContext, event: TraitEvent) {
+      if (event.type === 'catalog:search') {
+        const query = (event.payload?.query as string || '').toLowerCase();
+        const results = config.products.filter(p => p.name.toLowerCase().includes(query));
+        ctx.emit?.('catalog:results', { count: results.length, products: results.slice(0, config.pageSize) });
+      }
+      if (event.type === 'catalog:filter') {
+        const category = event.payload?.category as string;
+        const results = category ? config.products.filter(p => p.category === category) : config.products;
+        ctx.emit?.('catalog:filtered', { count: results.length, category });
+      }
+    },
+  };
+}

package/src/traits/ReturnTrait.ts

@@ -0,0 +1,23 @@
+/** @return Trait — Return and refund management. @trait return */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type ReturnStatus = 'requested' | 'approved' | 'shipped' | 'received' | 'refunded' | 'denied';
+export interface ReturnConfig { orderId: string; reason: string; status: ReturnStatus; refundAmount: number; returnWindowDays: number; }
+
+const defaultConfig: ReturnConfig = { orderId: '', reason: '', status: 'requested', refundAmount: 0, returnWindowDays: 30 };
+
+export function createReturnHandler(): TraitHandler<ReturnConfig> {
+  return {
+    name: 'return', defaultConfig,
+    onAttach(node: HSPlusNode, config: ReturnConfig, ctx: TraitContext) { node.__returnState = { ...config, requestedAt: Date.now() }; ctx.emit?.('return:created', { orderId: config.orderId }); },
+    onDetach(node: HSPlusNode, _c: ReturnConfig, ctx: TraitContext) { delete node.__returnState; ctx.emit?.('return:cancelled'); },
+    onUpdate() {},
+    onEvent(node: HSPlusNode, _c: ReturnConfig, ctx: TraitContext, event: TraitEvent) {
+      const s = node.__returnState as Record<string, unknown> | undefined; if (!s) return;
+      if (event.type === 'return:approve') { s.status = 'approved'; ctx.emit?.('return:approved'); }
+      if (event.type === 'return:ship') { s.status = 'shipped'; ctx.emit?.('return:shipped'); }
+      if (event.type === 'return:receive') { s.status = 'received'; ctx.emit?.('return:received'); }
+      if (event.type === 'return:refund') { s.status = 'refunded'; ctx.emit?.('return:refunded', { amount: s.refundAmount }); }
+    },
+  };
+}

package/src/traits/ShippingRateTrait.ts

@@ -0,0 +1,19 @@
+/** @shipping_rate Trait — Shipping cost calculation. @trait shipping_rate */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type ShippingMethod = 'standard' | 'express' | 'overnight' | 'freight' | 'pickup';
+export interface ShippingRateConfig { carrier: string; method: ShippingMethod; weightKg: number; dimensions: { lengthCm: number; widthCm: number; heightCm: number; }; origin: string; destination: string; rate: number; estimatedDays: number; }
+
+const defaultConfig: ShippingRateConfig = { carrier: '', method: 'standard', weightKg: 0, dimensions: { lengthCm: 0, widthCm: 0, heightCm: 0 }, origin: '', destination: '', rate: 0, estimatedDays: 5 };
+
+export function createShippingRateHandler(): TraitHandler<ShippingRateConfig> {
+  return {
+    name: 'shipping_rate', defaultConfig,
+    onAttach(node: HSPlusNode, config: ShippingRateConfig, ctx: TraitContext) { node.__shippingState = { calculatedRate: config.rate, carrier: config.carrier }; ctx.emit?.('shipping:rate_set', { rate: config.rate, method: config.method }); },
+    onDetach(node: HSPlusNode, _c: ShippingRateConfig, ctx: TraitContext) { delete node.__shippingState; ctx.emit?.('shipping:cleared'); },
+    onUpdate() {},
+    onEvent(_n: HSPlusNode, config: ShippingRateConfig, ctx: TraitContext, event: TraitEvent) {
+      if (event.type === 'shipping:calculate') { ctx.emit?.('shipping:calculated', { rate: config.rate, estimatedDays: config.estimatedDays, carrier: config.carrier }); }
+    },
+  };
+}

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; getState?: () => Record<string, unknown>; setState?: (updates: Record<string, unknown>) => void; [key: string]: unknown; }
+export interface TraitEvent { type: string; source?: string; payload?: Record<string, unknown>; [key: string]: unknown; }
+export interface TraitHandler<TConfig = unknown> { name: string; defaultConfig: TConfig; onAttach(node: HSPlusNode, config: TConfig, ctx: TraitContext): void; onDetach(node: HSPlusNode, config: TConfig, ctx: TraitContext): void; onUpdate(node: HSPlusNode, config: TConfig, ctx: TraitContext, delta: number): void; onEvent(node: HSPlusNode, config: TConfig, ctx: TraitContext, event: TraitEvent): void; }

package/tsconfig.json

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

package/vitest.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vitest/config';
+import { resolve } from 'path';
+
+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,
+  },
+});