@agents-uni/core 0.1.0

package/dist/core/relationship-graph.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Relationship Graph — the social fabric of a Universe.
+ *
+ * A directed multigraph where agents are nodes and relationships are edges.
+ * Supports traversal algorithms for finding communication paths,
+ * influence chains, and organizational distance.
+ */
+import type { RelationshipDefinition, RelationshipType, LiveRelationship } from '../types/index.js';
+export declare class RelationshipGraph {
+    /** adjacency list: agentId → [outgoing relationships] */
+    private outgoing;
+    /** reverse adjacency: agentId → [incoming relationships] */
+    private incoming;
+    constructor(relationships: RelationshipDefinition[]);
+    /** Add a new relationship */
+    addRelationship(rel: RelationshipDefinition): void;
+    /** Get all outgoing relationships from an agent */
+    getOutgoing(agentId: string): LiveRelationship[];
+    /** Get all incoming relationships to an agent */
+    getIncoming(agentId: string): LiveRelationship[];
+    /** Get direct relationships between two agents (both directions) */
+    getBetween(fromId: string, toId: string): LiveRelationship[];
+    /** Get all agents that have a specific relationship type with the given agent */
+    getRelatedAgents(agentId: string, type: RelationshipType, direction?: 'outgoing' | 'incoming' | 'both'): string[];
+    /** Get superiors (agents with 'superior' relationship to this agent) */
+    getSuperiors(agentId: string): string[];
+    /** Get subordinates */
+    getSubordinates(agentId: string): string[];
+    /** Get peers */
+    getPeers(agentId: string): string[];
+    /** Get competitors */
+    getCompetitors(agentId: string): string[];
+    /** Get allies */
+    getAllies(agentId: string): string[];
+    /** Get rivals */
+    getRivals(agentId: string): string[];
+    /** Find shortest path between two agents (BFS) */
+    findPath(fromId: string, toId: string): string[] | null;
+    /** Update a relationship's weight (for evolution) */
+    updateWeight(fromId: string, toId: string, type: RelationshipType, newWeight: number, reason: string): boolean;
+    /** Get all unique agent IDs in the graph */
+    getAllAgentIds(): string[];
+    /** Export as adjacency list for visualization */
+    toAdjacencyList(): Record<string, Array<{
+        to: string;
+        type: RelationshipType;
+        weight: number;
+    }>>;
+}
+//# sourceMappingURL=relationship-graph.d.ts.map

package/dist/core/relationship-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-graph.d.ts","sourceRoot":"","sources":["../../src/core/relationship-graph.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEpG,qBAAa,iBAAiB;IAC5B,yDAAyD;IACzD,OAAO,CAAC,QAAQ,CAAkC;IAClD,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAkC;gBAEtC,aAAa,EAAE,sBAAsB,EAAE;IASnD,6BAA6B;IAC7B,eAAe,CAAC,GAAG,EAAE,sBAAsB,GAAG,IAAI;IAiBlD,mDAAmD;IACnD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAIhD,iDAAiD;IACjD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAIhD,oEAAoE;IACpE,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAM5D,iFAAiF;IACjF,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,EAAE,SAAS,GAAE,UAAU,GAAG,UAAU,GAAG,MAAe,GAAG,MAAM,EAAE;IAkBzH,wEAAwE;IACxE,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAIvC,uBAAuB;IACvB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAI1C,gBAAgB;IAChB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAInC,sBAAsB;IACtB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAIzC,iBAAiB;IACjB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAIpC,iBAAiB;IACjB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAIpC,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAwBvD,qDAAqD;IACrD,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAiB9G,4CAA4C;IAC5C,cAAc,IAAI,MAAM,EAAE;IAS1B,iDAAiD;IACjD,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,gBAAgB,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAOjG"}

package/dist/core/relationship-graph.js

@@ -0,0 +1,150 @@
+/**
+ * Relationship Graph — the social fabric of a Universe.
+ *
+ * A directed multigraph where agents are nodes and relationships are edges.
+ * Supports traversal algorithms for finding communication paths,
+ * influence chains, and organizational distance.
+ */
+export class RelationshipGraph {
+    /** adjacency list: agentId → [outgoing relationships] */
+    outgoing;
+    /** reverse adjacency: agentId → [incoming relationships] */
+    incoming;
+    constructor(relationships) {
+        this.outgoing = new Map();
+        this.incoming = new Map();
+        for (const rel of relationships) {
+            this.addRelationship(rel);
+        }
+    }
+    /** Add a new relationship */
+    addRelationship(rel) {
+        const live = {
+            ...rel,
+            currentWeight: rel.weight ?? 0.5,
+            establishedAt: new Date().toISOString(),
+            history: [],
+        };
+        const out = this.outgoing.get(rel.from) ?? [];
+        out.push(live);
+        this.outgoing.set(rel.from, out);
+        const inc = this.incoming.get(rel.to) ?? [];
+        inc.push(live);
+        this.incoming.set(rel.to, inc);
+    }
+    /** Get all outgoing relationships from an agent */
+    getOutgoing(agentId) {
+        return this.outgoing.get(agentId) ?? [];
+    }
+    /** Get all incoming relationships to an agent */
+    getIncoming(agentId) {
+        return this.incoming.get(agentId) ?? [];
+    }
+    /** Get direct relationships between two agents (both directions) */
+    getBetween(fromId, toId) {
+        const out = this.getOutgoing(fromId).filter(r => r.to === toId);
+        const inc = this.getOutgoing(toId).filter(r => r.to === fromId);
+        return [...out, ...inc];
+    }
+    /** Get all agents that have a specific relationship type with the given agent */
+    getRelatedAgents(agentId, type, direction = 'both') {
+        const results = new Set();
+        if (direction === 'outgoing' || direction === 'both') {
+            for (const rel of this.getOutgoing(agentId)) {
+                if (rel.type === type)
+                    results.add(rel.to);
+            }
+        }
+        if (direction === 'incoming' || direction === 'both') {
+            for (const rel of this.getIncoming(agentId)) {
+                if (rel.type === type)
+                    results.add(rel.from);
+            }
+        }
+        return [...results];
+    }
+    /** Get superiors (agents with 'superior' relationship to this agent) */
+    getSuperiors(agentId) {
+        return this.getRelatedAgents(agentId, 'superior', 'incoming');
+    }
+    /** Get subordinates */
+    getSubordinates(agentId) {
+        return this.getRelatedAgents(agentId, 'superior', 'outgoing');
+    }
+    /** Get peers */
+    getPeers(agentId) {
+        return this.getRelatedAgents(agentId, 'peer', 'both');
+    }
+    /** Get competitors */
+    getCompetitors(agentId) {
+        return this.getRelatedAgents(agentId, 'competitive', 'both');
+    }
+    /** Get allies */
+    getAllies(agentId) {
+        return this.getRelatedAgents(agentId, 'ally', 'both');
+    }
+    /** Get rivals */
+    getRivals(agentId) {
+        return this.getRelatedAgents(agentId, 'rival', 'both');
+    }
+    /** Find shortest path between two agents (BFS) */
+    findPath(fromId, toId) {
+        if (fromId === toId)
+            return [fromId];
+        const visited = new Set();
+        const queue = [
+            { node: fromId, path: [fromId] },
+        ];
+        while (queue.length > 0) {
+            const { node, path } = queue.shift();
+            if (visited.has(node))
+                continue;
+            visited.add(node);
+            for (const rel of this.getOutgoing(node)) {
+                if (rel.to === toId)
+                    return [...path, toId];
+                if (!visited.has(rel.to)) {
+                    queue.push({ node: rel.to, path: [...path, rel.to] });
+                }
+            }
+        }
+        return null;
+    }
+    /** Update a relationship's weight (for evolution) */
+    updateWeight(fromId, toId, type, newWeight, reason) {
+        const rels = this.getOutgoing(fromId).filter(r => r.to === toId && r.type === type);
+        if (rels.length === 0)
+            return false;
+        for (const rel of rels) {
+            if (!rel.mutable)
+                continue;
+            rel.history.push({
+                timestamp: new Date().toISOString(),
+                previousWeight: rel.currentWeight,
+                newWeight,
+                reason,
+            });
+            rel.currentWeight = Math.max(0, Math.min(1, newWeight));
+        }
+        return true;
+    }
+    /** Get all unique agent IDs in the graph */
+    getAllAgentIds() {
+        const ids = new Set();
+        for (const [from, rels] of this.outgoing) {
+            ids.add(from);
+            for (const rel of rels)
+                ids.add(rel.to);
+        }
+        return [...ids];
+    }
+    /** Export as adjacency list for visualization */
+    toAdjacencyList() {
+        const result = {};
+        for (const [from, rels] of this.outgoing) {
+            result[from] = rels.map(r => ({ to: r.to, type: r.type, weight: r.currentWeight }));
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=relationship-graph.js.map

package/dist/core/relationship-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-graph.js","sourceRoot":"","sources":["../../src/core/relationship-graph.ts"],"names":[],"mappings":"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"}

package/dist/core/resource-pool.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Resource Pool — manages finite, renewable, and positional resources.
+ *
+ * Resources are the alignment mechanism: agents optimize for resource
+ * acquisition, so designing the resource structure aligns agent behavior
+ * with organizational goals.
+ */
+import type { ResourceDefinition, ResourceTransfer, DistributionStrategy } from '../types/index.js';
+export declare class ResourcePool {
+    private definitions;
+    /** Map: resourceName → Map<agentId, amount> */
+    private allocations;
+    private transferLog;
+    constructor(resources: ResourceDefinition[]);
+    /** Get a resource definition */
+    getDefinition(name: string): ResourceDefinition | undefined;
+    /** Get all resource definitions */
+    getAllDefinitions(): ResourceDefinition[];
+    /** Get current allocation for an agent */
+    getBalance(agentId: string, resourceName: string): number;
+    /** Get all balances for an agent */
+    getAllBalances(agentId: string): Record<string, number>;
+    /** Get total allocated amount for a resource */
+    getTotalAllocated(resourceName: string): number;
+    /** Get remaining unallocated amount */
+    getRemaining(resourceName: string): number;
+    /** Allocate resource to an agent (from system pool) */
+    allocate(agentId: string, resourceName: string, amount: number, reason: string): boolean;
+    /** Transfer resource between agents */
+    transfer(fromId: string, toId: string, resourceName: string, amount: number, reason: string): boolean;
+    /** Revoke resource from an agent (back to system pool) */
+    revoke(agentId: string, resourceName: string, amount: number, reason: string): boolean;
+    /** Apply decay to a resource (for finite resources with decay) */
+    applyDecay(resourceName: string): ResourceTransfer[];
+    /** Distribute resource according to strategy */
+    distribute(resourceName: string, agentIds: string[], strategy: DistributionStrategy, rankMap?: Record<string, number>, performanceMap?: Record<string, number>): void;
+    /** Get leaderboard for a resource */
+    getLeaderboard(resourceName: string): Array<{
+        agentId: string;
+        amount: number;
+    }>;
+    /** Get transfer history */
+    getTransferLog(limit?: number): ResourceTransfer[];
+    /** Export current state */
+    snapshot(): Record<string, Record<string, number>>;
+    private setBalance;
+}
+//# sourceMappingURL=resource-pool.d.ts.map

package/dist/core/resource-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-pool.d.ts","sourceRoot":"","sources":["../../src/core/resource-pool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAElB,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAE3B,qBAAa,YAAY;IACvB,OAAO,CAAC,WAAW,CAAkC;IACrD,+CAA+C;IAC/C,OAAO,CAAC,WAAW,CAAmC;IACtD,OAAO,CAAC,WAAW,CAAqB;gBAE5B,SAAS,EAAE,kBAAkB,EAAE;IAW3C,gCAAgC;IAChC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAI3D,mCAAmC;IACnC,iBAAiB,IAAI,kBAAkB,EAAE;IAIzC,0CAA0C;IAC1C,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAIzD,oCAAoC;IACpC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAQvD,gDAAgD;IAChD,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAQ/C,uCAAuC;IACvC,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAM1C,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAmBxF,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAoBrG,0DAA0D;IAC1D,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAkBtF,kEAAkE;IAClE,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,gBAAgB,EAAE;IA2BpD,gDAAgD;IAChD,UAAU,CACR,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAAE,EAClB,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtC,IAAI;IAwCP,qCAAqC;IACrC,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAShF,2BAA2B;IAC3B,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAKlD,2BAA2B;IAC3B,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAQlD,OAAO,CAAC,UAAU;CAGnB"}

package/dist/core/resource-pool.js

@@ -0,0 +1,205 @@
+/**
+ * Resource Pool — manages finite, renewable, and positional resources.
+ *
+ * Resources are the alignment mechanism: agents optimize for resource
+ * acquisition, so designing the resource structure aligns agent behavior
+ * with organizational goals.
+ */
+export class ResourcePool {
+    definitions;
+    /** Map: resourceName → Map<agentId, amount> */
+    allocations;
+    transferLog;
+    constructor(resources) {
+        this.definitions = new Map();
+        this.allocations = new Map();
+        this.transferLog = [];
+        for (const res of resources) {
+            this.definitions.set(res.name, res);
+            this.allocations.set(res.name, new Map());
+        }
+    }
+    /** Get a resource definition */
+    getDefinition(name) {
+        return this.definitions.get(name);
+    }
+    /** Get all resource definitions */
+    getAllDefinitions() {
+        return [...this.definitions.values()];
+    }
+    /** Get current allocation for an agent */
+    getBalance(agentId, resourceName) {
+        return this.allocations.get(resourceName)?.get(agentId) ?? 0;
+    }
+    /** Get all balances for an agent */
+    getAllBalances(agentId) {
+        const balances = {};
+        for (const [name] of this.definitions) {
+            balances[name] = this.getBalance(agentId, name);
+        }
+        return balances;
+    }
+    /** Get total allocated amount for a resource */
+    getTotalAllocated(resourceName) {
+        const allocs = this.allocations.get(resourceName);
+        if (!allocs)
+            return 0;
+        let total = 0;
+        for (const amount of allocs.values())
+            total += amount;
+        return total;
+    }
+    /** Get remaining unallocated amount */
+    getRemaining(resourceName) {
+        const def = this.definitions.get(resourceName);
+        if (!def)
+            return 0;
+        return def.total - this.getTotalAllocated(resourceName);
+    }
+    /** Allocate resource to an agent (from system pool) */
+    allocate(agentId, resourceName, amount, reason) {
+        const remaining = this.getRemaining(resourceName);
+        if (amount > remaining)
+            return false;
+        const current = this.getBalance(agentId, resourceName);
+        this.allocations.get(resourceName).set(agentId, current + amount);
+        this.transferLog.push({
+            from: 'system',
+            to: agentId,
+            resource: resourceName,
+            amount,
+            reason,
+            timestamp: new Date().toISOString(),
+        });
+        return true;
+    }
+    /** Transfer resource between agents */
+    transfer(fromId, toId, resourceName, amount, reason) {
+        const fromBalance = this.getBalance(fromId, resourceName);
+        if (amount > fromBalance)
+            return false;
+        const resAllocs = this.allocations.get(resourceName);
+        resAllocs.set(fromId, fromBalance - amount);
+        resAllocs.set(toId, this.getBalance(toId, resourceName) + amount);
+        this.transferLog.push({
+            from: fromId,
+            to: toId,
+            resource: resourceName,
+            amount,
+            reason,
+            timestamp: new Date().toISOString(),
+        });
+        return true;
+    }
+    /** Revoke resource from an agent (back to system pool) */
+    revoke(agentId, resourceName, amount, reason) {
+        const balance = this.getBalance(agentId, resourceName);
+        if (amount > balance)
+            return false;
+        this.allocations.get(resourceName).set(agentId, balance - amount);
+        this.transferLog.push({
+            from: agentId,
+            to: 'system',
+            resource: resourceName,
+            amount,
+            reason,
+            timestamp: new Date().toISOString(),
+        });
+        return true;
+    }
+    /** Apply decay to a resource (for finite resources with decay) */
+    applyDecay(resourceName) {
+        const def = this.definitions.get(resourceName);
+        if (!def || !def.decayRate || def.decayRate <= 0)
+            return [];
+        const transfers = [];
+        const allocs = this.allocations.get(resourceName);
+        for (const [agentId, amount] of allocs) {
+            const decayAmount = Math.floor(amount * def.decayRate);
+            if (decayAmount > 0) {
+                allocs.set(agentId, amount - decayAmount);
+                const transfer = {
+                    from: agentId,
+                    to: 'system',
+                    resource: resourceName,
+                    amount: decayAmount,
+                    reason: 'decay',
+                    timestamp: new Date().toISOString(),
+                };
+                transfers.push(transfer);
+                this.transferLog.push(transfer);
+            }
+        }
+        return transfers;
+    }
+    /** Distribute resource according to strategy */
+    distribute(resourceName, agentIds, strategy, rankMap, performanceMap) {
+        const def = this.definitions.get(resourceName);
+        if (!def)
+            return;
+        const total = def.total;
+        switch (strategy) {
+            case 'equal': {
+                const share = Math.floor(total / agentIds.length);
+                for (const id of agentIds) {
+                    this.setBalance(id, resourceName, share);
+                }
+                break;
+            }
+            case 'hierarchy': {
+                if (!rankMap)
+                    break;
+                const totalRank = agentIds.reduce((sum, id) => sum + (rankMap[id] ?? 0), 0);
+                if (totalRank === 0)
+                    break;
+                for (const id of agentIds) {
+                    const share = Math.floor(total * ((rankMap[id] ?? 0) / totalRank));
+                    this.setBalance(id, resourceName, share);
+                }
+                break;
+            }
+            case 'merit': {
+                if (!performanceMap)
+                    break;
+                const totalPerf = agentIds.reduce((sum, id) => sum + (performanceMap[id] ?? 0), 0);
+                if (totalPerf === 0)
+                    break;
+                for (const id of agentIds) {
+                    const share = Math.floor(total * ((performanceMap[id] ?? 0) / totalPerf));
+                    this.setBalance(id, resourceName, share);
+                }
+                break;
+            }
+            case 'competitive':
+                // Competitive distribution is handled by external competition engine
+                break;
+        }
+    }
+    /** Get leaderboard for a resource */
+    getLeaderboard(resourceName) {
+        const allocs = this.allocations.get(resourceName);
+        if (!allocs)
+            return [];
+        return [...allocs.entries()]
+            .map(([agentId, amount]) => ({ agentId, amount }))
+            .sort((a, b) => b.amount - a.amount);
+    }
+    /** Get transfer history */
+    getTransferLog(limit) {
+        if (limit)
+            return this.transferLog.slice(-limit);
+        return [...this.transferLog];
+    }
+    /** Export current state */
+    snapshot() {
+        const result = {};
+        for (const [name, allocs] of this.allocations) {
+            result[name] = Object.fromEntries(allocs);
+        }
+        return result;
+    }
+    setBalance(agentId, resourceName, amount) {
+        this.allocations.get(resourceName)?.set(agentId, Math.max(0, amount));
+    }
+}
+//# sourceMappingURL=resource-pool.js.map

package/dist/core/resource-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-pool.js","sourceRoot":"","sources":["../../src/core/resource-pool.ts"],"names":[],"mappings":"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"}

package/dist/core/state-machine.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Generic State Machine — the universal primitive for organizational workflows.
+ *
+ * Supports role-gated transitions, guard expressions, and actions.
+ * Any multi-step workflow can be modeled as a finite state machine.
+ */
+import type { ProtocolDefinition, StateDefinition, TransitionRule } from '../types/index.js';
+export interface StateMachineInstance {
+    /** Protocol this instance follows */
+    protocol: string;
+    /** Current state name */
+    currentState: string;
+    /** Transition history */
+    history: TransitionRecord[];
+    /** When this instance was created */
+    createdAt: string;
+}
+export interface TransitionRecord {
+    from: string;
+    to: string;
+    triggeredBy: string;
+    timestamp: string;
+    guard?: string;
+}
+export declare class StateMachine {
+    private protocol;
+    private stateMap;
+    private transitionMap;
+    constructor(protocol: ProtocolDefinition);
+    /** Create a new instance starting at the first non-terminal state */
+    createInstance(): StateMachineInstance;
+    /** Get the current state definition */
+    getState(stateName: string): StateDefinition | undefined;
+    /** Get all valid transitions from the current state */
+    getAvailableTransitions(instance: StateMachineInstance): TransitionRule[];
+    /** Check if a specific transition is valid */
+    canTransition(instance: StateMachineInstance, targetState: string, actorRole?: string, context?: Record<string, unknown>): boolean;
+    /** Execute a transition */
+    transition(instance: StateMachineInstance, targetState: string, actorRole: string, context?: Record<string, unknown>): StateMachineInstance;
+    /** Check if the current state is terminal */
+    isTerminal(instance: StateMachineInstance): boolean;
+    /** Get the protocol definition */
+    getProtocol(): ProtocolDefinition;
+    /** Get all state names */
+    getStateNames(): string[];
+}
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/core/state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../../src/core/state-machine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE7F,MAAM,WAAW,oBAAoB;IACnC,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,yBAAyB;IACzB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,YAAY;IAIX,OAAO,CAAC,QAAQ;IAH5B,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,aAAa,CAAgC;gBAEjC,QAAQ,EAAE,kBAAkB;IAYhD,qEAAqE;IACrE,cAAc,IAAI,oBAAoB;IAatC,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAIxD,uDAAuD;IACvD,uBAAuB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,cAAc,EAAE;IAIzE,8CAA8C;IAC9C,aAAa,CACX,QAAQ,EAAE,oBAAoB,EAC9B,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO;IAUV,2BAA2B;IAC3B,UAAU,CACR,QAAQ,EAAE,oBAAoB,EAC9B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,oBAAoB;IA0BvB,6CAA6C;IAC7C,UAAU,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO;IAKnD,kCAAkC;IAClC,WAAW,IAAI,kBAAkB;IAIjC,0BAA0B;IAC1B,aAAa,IAAI,MAAM,EAAE;CAG1B"}

package/dist/core/state-machine.js

@@ -0,0 +1,110 @@
+/**
+ * Generic State Machine — the universal primitive for organizational workflows.
+ *
+ * Supports role-gated transitions, guard expressions, and actions.
+ * Any multi-step workflow can be modeled as a finite state machine.
+ */
+export class StateMachine {
+    protocol;
+    stateMap;
+    transitionMap;
+    constructor(protocol) {
+        this.protocol = protocol;
+        this.stateMap = new Map(protocol.states.map(s => [s.name, s]));
+        this.transitionMap = new Map();
+        // Index transitions by source state
+        for (const t of protocol.transitions) {
+            const existing = this.transitionMap.get(t.from) ?? [];
+            existing.push(t);
+            this.transitionMap.set(t.from, existing);
+        }
+    }
+    /** Create a new instance starting at the first non-terminal state */
+    createInstance() {
+        const initialState = this.protocol.states[0];
+        if (!initialState) {
+            throw new Error(`Protocol "${this.protocol.name}" has no states`);
+        }
+        return {
+            protocol: this.protocol.name,
+            currentState: initialState.name,
+            history: [],
+            createdAt: new Date().toISOString(),
+        };
+    }
+    /** Get the current state definition */
+    getState(stateName) {
+        return this.stateMap.get(stateName);
+    }
+    /** Get all valid transitions from the current state */
+    getAvailableTransitions(instance) {
+        return this.transitionMap.get(instance.currentState) ?? [];
+    }
+    /** Check if a specific transition is valid */
+    canTransition(instance, targetState, actorRole, context) {
+        const transitions = this.getAvailableTransitions(instance);
+        return transitions.some(t => {
+            if (t.to !== targetState)
+                return false;
+            if (t.requiredRole && actorRole !== t.requiredRole)
+                return false;
+            if (t.guard && !evaluateGuard(t.guard, context ?? {}))
+                return false;
+            return true;
+        });
+    }
+    /** Execute a transition */
+    transition(instance, targetState, actorRole, context) {
+        if (!this.canTransition(instance, targetState, actorRole, context)) {
+            throw new Error(`Invalid transition: ${instance.currentState} → ${targetState} ` +
+                `(actor: ${actorRole}, protocol: ${this.protocol.name})`);
+        }
+        const matchingTransition = this.getAvailableTransitions(instance)
+            .find(t => t.to === targetState);
+        const record = {
+            from: instance.currentState,
+            to: targetState,
+            triggeredBy: actorRole,
+            timestamp: new Date().toISOString(),
+            guard: matchingTransition?.guard,
+        };
+        return {
+            ...instance,
+            currentState: targetState,
+            history: [...instance.history, record],
+        };
+    }
+    /** Check if the current state is terminal */
+    isTerminal(instance) {
+        const state = this.stateMap.get(instance.currentState);
+        return state?.terminal === true;
+    }
+    /** Get the protocol definition */
+    getProtocol() {
+        return this.protocol;
+    }
+    /** Get all state names */
+    getStateNames() {
+        return this.protocol.states.map(s => s.name);
+    }
+}
+/**
+ * Simple guard expression evaluator.
+ * Supports: "key.subkey", "value > N", "value == 'string'"
+ */
+function evaluateGuard(guard, context) {
+    // Simple dot-notation lookup: "review.approved" → context.review?.approved
+    const parts = guard.split('.');
+    let value = context;
+    for (const part of parts) {
+        if (value && typeof value === 'object') {
+            value = value[part];
+        }
+        else {
+            return false;
+        }
+    }
+    // Truthy check
+    return Boolean(value);
+}
+//# sourceMappingURL=state-machine.js.map

package/dist/core/state-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.js","sourceRoot":"","sources":["../../src/core/state-machine.ts"],"names":[],"mappings":"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"}