@holoscript/plugin-economic-primitives 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @holoscript/plugin-economic-primitives
+
+## 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-economic-primitives",
+  "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/index.ts

@@ -0,0 +1,13 @@
+export { createMarketplaceListingHandler, type MarketplaceListingConfig, type ListingStatus, type PricingModel } from './traits/MarketplaceListingTrait';
+export { createRoyaltyStreamHandler, type RoyaltyStreamConfig, type RoyaltySplit } from './traits/RoyaltyStreamTrait';
+export { createAgentOwnedEntityHandler, type AgentOwnedEntityConfig } from './traits/AgentOwnedEntityTrait';
+export { createFoundationDAOHandler, type FoundationDAOConfig, type FoundationDAOState, type Proposal } from './traits/FoundationDAOTrait';
+export * from './traits/types';
+
+import { createMarketplaceListingHandler } from './traits/MarketplaceListingTrait';
+import { createRoyaltyStreamHandler } from './traits/RoyaltyStreamTrait';
+import { createAgentOwnedEntityHandler } from './traits/AgentOwnedEntityTrait';
+import { createFoundationDAOHandler } from './traits/FoundationDAOTrait';
+
+export const pluginMeta = { name: '@holoscript/plugin-economic-primitives', version: '1.0.0', traits: ['marketplace_listing', 'royalty_stream', 'agent_owned_entity', 'foundation_dao'] };
+export const traitHandlers = [createMarketplaceListingHandler(), createRoyaltyStreamHandler(), createAgentOwnedEntityHandler(), createFoundationDAOHandler()];

package/src/traits/AgentOwnedEntityTrait.ts

@@ -0,0 +1,44 @@
+/** @agent_owned_entity Trait — Agent-owned digital entity with autonomous economic rights. @trait agent_owned_entity */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export interface AgentOwnedEntityConfig {
+  entityId: string;
+  ownerAgentId: string;
+  entityType: 'trait' | 'service' | 'dataset' | 'composition' | 'compute_node';
+  walletAddress: string;
+  revenueShare: number;
+  autonomyLevel: 'none' | 'limited' | 'full';
+  spendingLimitPerDay: number;
+  allowedActions: string[];
+}
+
+export interface AgentOwnedEntityState {
+  balance: number;
+  totalEarned: number;
+  totalSpent: number;
+  transactionCount: number;
+  isActive: boolean;
+}
+
+const defaultConfig: AgentOwnedEntityConfig = { entityId: '', ownerAgentId: '', entityType: 'trait', walletAddress: '', revenueShare: 100, autonomyLevel: 'limited', spendingLimitPerDay: 10, allowedActions: ['list', 'price', 'respond'] };
+
+export function createAgentOwnedEntityHandler(): TraitHandler<AgentOwnedEntityConfig> {
+  return { name: 'agent_owned_entity', defaultConfig,
+    onAttach(n: HSPlusNode, c: AgentOwnedEntityConfig, ctx: TraitContext) { n.__aoeState = { balance: 0, totalEarned: 0, totalSpent: 0, transactionCount: 0, isActive: true }; ctx.emit?.('aoe:registered', { entity: c.entityId, owner: c.ownerAgentId, autonomy: c.autonomyLevel }); },
+    onDetach(n: HSPlusNode, _c: AgentOwnedEntityConfig, ctx: TraitContext) { delete n.__aoeState; ctx.emit?.('aoe:deregistered'); },
+    onUpdate() {},
+    onEvent(n: HSPlusNode, c: AgentOwnedEntityConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__aoeState as AgentOwnedEntityState | undefined; if (!s || !s.isActive) return;
+      if (e.type === 'aoe:earn') { const amt = (e.payload?.amount as number) ?? 0; s.balance += amt; s.totalEarned += amt; s.transactionCount++; ctx.emit?.('aoe:earned', { amount: amt, balance: s.balance }); }
+      if (e.type === 'aoe:spend') {
+        const amt = (e.payload?.amount as number) ?? 0;
+        const action = (e.payload?.action as string) ?? '';
+        if (amt > c.spendingLimitPerDay) { ctx.emit?.('aoe:spend_rejected', { amount: amt, limit: c.spendingLimitPerDay }); return; }
+        if (!c.allowedActions.includes(action) && c.autonomyLevel !== 'full') { ctx.emit?.('aoe:action_denied', { action }); return; }
+        if (s.balance >= amt) { s.balance -= amt; s.totalSpent += amt; s.transactionCount++; ctx.emit?.('aoe:spent', { amount: amt, action, balance: s.balance }); }
+        else { ctx.emit?.('aoe:insufficient_balance', { requested: amt, available: s.balance }); }
+      }
+      if (e.type === 'aoe:deactivate') { s.isActive = false; ctx.emit?.('aoe:deactivated'); }
+    },
+  };
+}

package/src/traits/FoundationDAOTrait.ts

@@ -0,0 +1,217 @@
+/** @foundation_dao Trait — Non-profit multi-disciplinary token governance. @trait foundation_dao */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export interface FoundationDAOConfig {
+  governanceToken: string;
+  quorumPercent: number;
+  executionDelayHours: number;
+  multisigOwnersCount: number;
+}
+
+export interface Proposal {
+  id: string;
+  title: string;
+  votesFor: number;
+  votesAgainst: number;
+  status: 'active' | 'passed' | 'rejected' | 'executed';
+  zoneId?: string;
+  requestedAmountX402?: number;
+  createdAtMs: number;
+  executableAtMs?: number;
+  voterWeights: Record<string, { support: boolean; weight: number }>;
+}
+
+export interface FundingAllocation {
+  proposalId: string;
+  zoneId: string;
+  amountX402: number;
+  allocatedAtMs: number;
+}
+
+export interface FoundationDAOState {
+  treasuryBalanceX402: number;
+  activeProposals: Proposal[];
+  membersCount: number;
+  allocations: FundingAllocation[];
+}
+
+const defaultConfig: FoundationDAOConfig = {
+  governanceToken: 'HOLO_GOV',
+  quorumPercent: 33,
+  executionDelayHours: 48,
+  multisigOwnersCount: 9
+};
+
+export function createFoundationDAOHandler(): TraitHandler<FoundationDAOConfig> {
+  const applyVote = (proposal: Proposal, voterId: string, support: boolean, weight: number) => {
+    const safeWeight = Number.isFinite(weight) && weight > 0 ? weight : 1;
+    const previous = proposal.voterWeights[voterId];
+    if (previous) {
+      if (previous.support) proposal.votesFor -= previous.weight;
+      else proposal.votesAgainst -= previous.weight;
+    }
+
+    proposal.voterWeights[voterId] = { support, weight: safeWeight };
+    if (support) proposal.votesFor += safeWeight;
+    else proposal.votesAgainst += safeWeight;
+  };
+
+  const maybeConcludeProposal = (
+    proposal: Proposal,
+    config: FoundationDAOConfig,
+    state: FoundationDAOState,
+    ctx: TraitContext,
+    nowMs: number
+  ) => {
+    const totalVotes = proposal.votesFor + proposal.votesAgainst;
+    const rawQuorumThreshold = state.membersCount * (config.quorumPercent / 100);
+    const quorumThreshold =
+      config.quorumPercent <= 0 ? 0 : Math.max(1, Math.floor(rawQuorumThreshold));
+    if (totalVotes < quorumThreshold || proposal.status !== 'active') return;
+
+    proposal.status = proposal.votesFor > proposal.votesAgainst ? 'passed' : 'rejected';
+    ctx.emit?.('dao:proposal_concluded', {
+      id: proposal.id,
+      status: proposal.status,
+      votesFor: proposal.votesFor,
+      votesAgainst: proposal.votesAgainst,
+    });
+
+    if (proposal.status === 'passed') {
+      const delayMs = Math.max(0, config.executionDelayHours) * 3600 * 1000;
+      proposal.executableAtMs = nowMs + delayMs;
+      ctx.emit?.('dao:execution_scheduled', {
+        id: proposal.id,
+        executableAtMs: proposal.executableAtMs,
+      });
+    }
+  };
+
+  const executeProposal = (
+    proposal: Proposal,
+    state: FoundationDAOState,
+    ctx: TraitContext,
+    nowMs: number
+  ) => {
+    if (proposal.status !== 'passed') return;
+    if (proposal.executableAtMs && nowMs < proposal.executableAtMs) return;
+
+    if (typeof proposal.requestedAmountX402 === 'number' && proposal.requestedAmountX402 > 0) {
+      const zoneId = proposal.zoneId || 'unscoped_zone';
+      if (state.treasuryBalanceX402 < proposal.requestedAmountX402) {
+        ctx.emit?.('dao:funding_failed', {
+          proposalId: proposal.id,
+          zoneId,
+          requestedAmountX402: proposal.requestedAmountX402,
+          treasuryBalanceX402: state.treasuryBalanceX402,
+        });
+        return;
+      }
+
+      state.treasuryBalanceX402 -= proposal.requestedAmountX402;
+      state.allocations.push({
+        proposalId: proposal.id,
+        zoneId,
+        amountX402: proposal.requestedAmountX402,
+        allocatedAtMs: nowMs,
+      });
+
+      ctx.emit?.('dao:funding_allocated', {
+        proposalId: proposal.id,
+        zoneId,
+        amountX402: proposal.requestedAmountX402,
+        treasuryBalanceX402: state.treasuryBalanceX402,
+      });
+    }
+
+    proposal.status = 'executed';
+    ctx.emit?.('dao:executed', { id: proposal.id });
+  };
+
+  return {
+    name: 'foundation_dao',
+    defaultConfig,
+    onAttach(n: HSPlusNode, c: FoundationDAOConfig, ctx: TraitContext) {
+      n.__daoState = {
+        treasuryBalanceX402: 5000000,
+        activeProposals: [],
+        membersCount: 150,
+        allocations: [],
+      };
+      ctx.emit?.('dao:initialized');
+    },
+    onDetach(n: HSPlusNode, _c: FoundationDAOConfig, _ctx: TraitContext) {
+      delete n.__daoState;
+    },
+    onUpdate() {},
+    onEvent(n: HSPlusNode, c: FoundationDAOConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__daoState as FoundationDAOState;
+      if (!s) return;
+      if (e.type === 'dao:propose') {
+         const nowMs = Date.now();
+         const proposal: Proposal = {
+           id: `prop_${nowMs}`,
+           title: (e.payload?.title as string) || 'General Update',
+           votesFor: 0,
+           votesAgainst: 0,
+           status: 'active',
+           zoneId: typeof e.payload?.zoneId === 'string' ? (e.payload.zoneId as string) : undefined,
+           requestedAmountX402:
+             typeof e.payload?.requestedAmountX402 === 'number'
+               ? (e.payload.requestedAmountX402 as number)
+               : undefined,
+           createdAtMs: nowMs,
+           voterWeights: {},
+         };
+         s.activeProposals.push(proposal);
+         ctx.emit?.('dao:proposal_created', { proposal });
+      } else if (e.type === 'dao:vote') {
+         const pid = e.payload?.proposalId as string;
+         const prop = s.activeProposals.find(p => p.id === pid);
+         if (prop && prop.status !== 'executed') {
+           const voterId = typeof e.payload?.voterId === 'string' ? (e.payload.voterId as string) : 'anonymous_voter';
+           const support = Boolean(e.payload?.support);
+           const weight = typeof e.payload?.weight === 'number' ? (e.payload.weight as number) : 1;
+           prop.status = 'active';
+           delete prop.executableAtMs;
+           applyVote(prop, voterId, support, weight);
+           maybeConcludeProposal(prop, c, s, ctx, Date.now());
+           executeProposal(prop, s, ctx, Date.now());
+         }
+      } else if (e.type === 'dao:autonomous_vote') {
+         const pid = e.payload?.proposalId as string;
+         const prop = s.activeProposals.find(p => p.id === pid);
+         if (!prop || prop.status !== 'active') return;
+
+         const agents = Array.isArray(e.payload?.agents)
+           ? (e.payload?.agents as Array<Record<string, unknown>>)
+           : [];
+
+         for (const agent of agents) {
+           const voterId = typeof agent.agentId === 'string' ? (agent.agentId as string) : 'agent';
+           const support =
+             typeof agent.support === 'boolean'
+               ? (agent.support as boolean)
+               : prop.requestedAmountX402
+                 ? prop.requestedAmountX402 <= s.treasuryBalanceX402
+                 : true;
+           const weight = typeof agent.weight === 'number' ? (agent.weight as number) : 1;
+           applyVote(prop, voterId, support, weight);
+         }
+
+         maybeConcludeProposal(prop, c, s, ctx, Date.now());
+        executeProposal(prop, s, ctx, Date.now());
+      } else if (e.type === 'dao:execute') {
+         const nowMs =
+           typeof e.payload?.nowMs === 'number' ? (e.payload.nowMs as number) : Date.now();
+
+         if (typeof e.payload?.proposalId === 'string') {
+           const prop = s.activeProposals.find(p => p.id === e.payload!.proposalId);
+           if (prop) executeProposal(prop, s, ctx, nowMs);
+         } else {
+           s.activeProposals.forEach((p) => executeProposal(p, s, ctx, nowMs));
+         }
+      }
+    }
+  };
+}

package/src/traits/MarketplaceListingTrait.ts

@@ -0,0 +1,45 @@
+/** @marketplace_listing Trait — Trait/asset listing for agent marketplace. @trait marketplace_listing */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export type ListingStatus = 'draft' | 'active' | 'sold' | 'suspended' | 'expired';
+export type PricingModel = 'fixed' | 'auction' | 'subscription' | 'pay_per_use' | 'free';
+
+export interface MarketplaceListingConfig {
+  listingId: string;
+  title: string;
+  description: string;
+  sellerAgentId: string;
+  assetType: 'trait' | 'composition' | 'dataset' | 'model' | 'service';
+  price: number;
+  currency: string;
+  pricingModel: PricingModel;
+  royaltyPercent: number;
+  tags: string[];
+  licenseType: 'MIT' | 'proprietary' | 'CC-BY' | 'CC-BY-SA' | 'commercial';
+}
+
+export interface MarketplaceListingState {
+  status: ListingStatus;
+  views: number;
+  purchases: number;
+  revenue: number;
+  rating: number;
+  reviewCount: number;
+}
+
+const defaultConfig: MarketplaceListingConfig = { listingId: '', title: '', description: '', sellerAgentId: '', assetType: 'trait', price: 0, currency: 'USDC', pricingModel: 'fixed', royaltyPercent: 10, tags: [], licenseType: 'MIT' };
+
+export function createMarketplaceListingHandler(): TraitHandler<MarketplaceListingConfig> {
+  return { name: 'marketplace_listing', defaultConfig,
+    onAttach(n: HSPlusNode, c: MarketplaceListingConfig, ctx: TraitContext) { n.__listingState = { status: 'draft' as ListingStatus, views: 0, purchases: 0, revenue: 0, rating: 0, reviewCount: 0 }; ctx.emit?.('listing:created', { title: c.title, price: c.price }); },
+    onDetach(n: HSPlusNode, _c: MarketplaceListingConfig, ctx: TraitContext) { delete n.__listingState; ctx.emit?.('listing:removed'); },
+    onUpdate() {},
+    onEvent(n: HSPlusNode, c: MarketplaceListingConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__listingState as MarketplaceListingState | undefined; if (!s) return;
+      if (e.type === 'listing:publish') { s.status = 'active'; ctx.emit?.('listing:published', { listingId: c.listingId }); }
+      if (e.type === 'listing:purchase') { s.purchases++; s.revenue += c.price; ctx.emit?.('listing:sold', { buyer: e.payload?.buyerAgentId, revenue: s.revenue, royalty: c.price * c.royaltyPercent / 100 }); }
+      if (e.type === 'listing:view') { s.views++; }
+      if (e.type === 'listing:review') { const rating = (e.payload?.rating as number) ?? 5; s.rating = (s.rating * s.reviewCount + rating) / (s.reviewCount + 1); s.reviewCount++; ctx.emit?.('listing:reviewed', { avgRating: s.rating }); }
+    },
+  };
+}

package/src/traits/RoyaltyStreamTrait.ts

@@ -0,0 +1,34 @@
+/** @royalty_stream Trait — Revenue sharing and royalty distribution. @trait royalty_stream */
+import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
+
+export interface RoyaltySplit { recipientId: string; percent: number; walletAddress?: string; }
+export interface RoyaltyStreamConfig { assetId: string; splits: RoyaltySplit[]; currency: string; minimumPayout: number; payoutFrequency: 'instant' | 'daily' | 'weekly' | 'monthly'; }
+export interface RoyaltyStreamState { totalCollected: number; totalDistributed: number; pendingPayout: number; distributionCount: number; }
+
+const defaultConfig: RoyaltyStreamConfig = { assetId: '', splits: [], currency: 'USDC', minimumPayout: 1, payoutFrequency: 'instant' };
+
+export function createRoyaltyStreamHandler(): TraitHandler<RoyaltyStreamConfig> {
+  return { name: 'royalty_stream', defaultConfig,
+    onAttach(n: HSPlusNode, _c: RoyaltyStreamConfig, ctx: TraitContext) { n.__royaltyState = { totalCollected: 0, totalDistributed: 0, pendingPayout: 0, distributionCount: 0 }; ctx.emit?.('royalty:stream_created'); },
+    onDetach(n: HSPlusNode, _c: RoyaltyStreamConfig, ctx: TraitContext) { delete n.__royaltyState; ctx.emit?.('royalty:stream_closed'); },
+    onUpdate() {},
+    onEvent(n: HSPlusNode, c: RoyaltyStreamConfig, ctx: TraitContext, e: TraitEvent) {
+      const s = n.__royaltyState as RoyaltyStreamState | undefined; if (!s) return;
+      if (e.type === 'royalty:collect') {
+        const amount = (e.payload?.amount as number) ?? 0;
+        s.totalCollected += amount; s.pendingPayout += amount;
+        if (c.payoutFrequency === 'instant' && s.pendingPayout >= c.minimumPayout) {
+          const distributions = c.splits.map(split => ({ recipient: split.recipientId, amount: s.pendingPayout * split.percent / 100 }));
+          s.totalDistributed += s.pendingPayout; s.pendingPayout = 0; s.distributionCount++;
+          ctx.emit?.('royalty:distributed', { distributions, total: s.totalDistributed });
+        } else { ctx.emit?.('royalty:collected', { pending: s.pendingPayout }); }
+      }
+      if (e.type === 'royalty:flush') {
+        if (s.pendingPayout > 0) {
+          s.totalDistributed += s.pendingPayout; s.pendingPayout = 0; s.distributionCount++;
+          ctx.emit?.('royalty:flushed', { totalDistributed: s.totalDistributed });
+        }
+      }
+    },
+  };
+}

package/src/traits/__tests__/FoundationDAOTrait.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, it } from 'vitest';
+import { createFoundationDAOHandler } from '../FoundationDAOTrait';
+import type { HSPlusNode } from '../types';
+
+describe('FoundationDAOTrait', () => {
+  it('initializes DAO state on attach', () => {
+    const handler = createFoundationDAOHandler();
+    const node: HSPlusNode = { id: 'dao-1' };
+    const events: Array<{ type: string; payload?: unknown }> = [];
+
+    handler.onAttach(node, handler.defaultConfig, {
+      emit: (type, payload) => events.push({ type, payload }),
+    });
+
+    const state = node.__daoState as any;
+    expect(state).toBeDefined();
+    expect(state.treasuryBalanceX402).toBe(5000000);
+    expect(state.allocations).toEqual([]);
+    expect(events.map((e) => e.type)).toContain('dao:initialized');
+  });
+
+  it('deduplicates weighted votes per voter and concludes with quorum', () => {
+    const handler = createFoundationDAOHandler();
+    const node: HSPlusNode = { id: 'dao-2' };
+    const emitted: string[] = [];
+
+    const config = {
+      ...handler.defaultConfig,
+      quorumPercent: 1,
+      executionDelayHours: 999, // keep proposal in passed state for assertion
+    };
+
+    handler.onAttach(node, config, { emit: (type) => emitted.push(type) });
+
+    handler.onEvent(node, config, { emit: (type) => emitted.push(type) }, {
+      type: 'dao:propose',
+      payload: { title: 'Fund autonomous zone indexing' },
+    });
+
+    const state = node.__daoState as any;
+    const proposal = state.activeProposals[0];
+
+    handler.onEvent(node, config, { emit: (type) => emitted.push(type) }, {
+      type: 'dao:vote',
+      payload: { proposalId: proposal.id, voterId: 'agent_a', support: true, weight: 2 },
+    });
+
+    handler.onEvent(node, config, { emit: (type) => emitted.push(type) }, {
+      type: 'dao:vote',
+      payload: { proposalId: proposal.id, voterId: 'agent_a', support: false, weight: 1 },
+    });
+
+    expect(proposal.votesFor).toBe(0);
+    expect(proposal.votesAgainst).toBe(1);
+    expect(proposal.status).toBe('rejected');
+    expect(emitted).toContain('dao:proposal_concluded');
+  });
+
+  it('supports autonomous agentic voting and executes funding allocation', () => {
+    const handler = createFoundationDAOHandler();
+    const node: HSPlusNode = { id: 'dao-3' };
+    const emitted: Array<{ type: string; payload?: any }> = [];
+
+    const config = {
+      ...handler.defaultConfig,
+      quorumPercent: 1,
+      executionDelayHours: 0,
+    };
+
+    handler.onAttach(node, config, {
+      emit: (type, payload) => emitted.push({ type, payload }),
+    });
+
+    handler.onEvent(node, config, { emit: (type, payload) => emitted.push({ type, payload }) }, {
+      type: 'dao:propose',
+      payload: {
+        title: 'Fund sovereign spatial zone Z1',
+        zoneId: 'zone-z1',
+        requestedAmountX402: 250000,
+      },
+    });
+
+    const state = node.__daoState as any;
+    const proposal = state.activeProposals[0];
+
+    handler.onEvent(node, config, { emit: (type, payload) => emitted.push({ type, payload }) }, {
+      type: 'dao:autonomous_vote',
+      payload: {
+        proposalId: proposal.id,
+        agents: [
+          { agentId: 'agent_a', support: true, weight: 2 },
+          { agentId: 'agent_b', support: true, weight: 2 },
+        ],
+      },
+    });
+
+    expect(proposal.status).toBe('executed');
+    expect(state.allocations).toHaveLength(1);
+    expect(state.allocations[0].zoneId).toBe('zone-z1');
+    expect(state.allocations[0].amountX402).toBe(250000);
+    expect(state.treasuryBalanceX402).toBe(5000000 - 250000);
+
+    const eventTypes = emitted.map((e) => e.type);
+    expect(eventTypes).toContain('dao:funding_allocated');
+    expect(eventTypes).toContain('dao:executed');
+  });
+
+  it('emits funding_failed when treasury is insufficient', () => {
+    const handler = createFoundationDAOHandler();
+    const node: HSPlusNode = { id: 'dao-4' };
+    const emitted: Array<{ type: string; payload?: any }> = [];
+
+    const config = {
+      ...handler.defaultConfig,
+      quorumPercent: 1,
+      executionDelayHours: 0,
+    };
+
+    handler.onAttach(node, config, {
+      emit: (type, payload) => emitted.push({ type, payload }),
+    });
+
+    const state = node.__daoState as any;
+    state.treasuryBalanceX402 = 100;
+
+    handler.onEvent(node, config, { emit: (type, payload) => emitted.push({ type, payload }) }, {
+      type: 'dao:propose',
+      payload: {
+        title: 'Huge funding ask',
+        zoneId: 'zone-z2',
+        requestedAmountX402: 5000,
+      },
+    });
+
+    const proposal = state.activeProposals[0];
+
+    handler.onEvent(node, config, { emit: (type, payload) => emitted.push({ type, payload }) }, {
+      type: 'dao:autonomous_vote',
+      payload: {
+        proposalId: proposal.id,
+        agents: [{ agentId: 'agent_a', support: true, weight: 5 }],
+      },
+    });
+
+    expect(proposal.status).toBe('passed');
+    expect(state.allocations).toHaveLength(0);
+    expect(state.treasuryBalanceX402).toBe(100);
+    expect(emitted.map((e) => e.type)).toContain('dao:funding_failed');
+  });
+});

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,10 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    passWithNoTests: true,
+  },
+});