@arcanea/council 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @arcanea/council — Type Definitions
+ *
+ * Rebranded from claude-flow swarm types to Arcanea Council terminology.
+ * Consensus algorithms become Council protocols. Swarm topology becomes
+ * Guardian Council formation. Queen becomes Shinkami.
+ *
+ * Backward-compatible interfaces (ConsensusProposal, ConsensusVote,
+ * ConsensusResult) preserve the original claude-flow field names so
+ * ported consensus implementations work without modification.
+ */
+import { EventEmitter } from 'node:events';
+import type { GuardianName, Element } from './external-types.js';
+/**
+ * Available consensus protocols.
+ * - council-vote (Raft) — Leader-based, one Guardian leads
+ * - shinkamis-decree (Byzantine) — Fault-tolerant under hostile agents
+ * - whisper (Gossip) — Eventual consistency via propagation
+ * - gate-quorum (NEW) — Frequency-weighted voting across Guardians
+ * - ancient-accord (Paxos) — Falls back to Raft
+ */
+export type CouncilProtocol = 'council-vote' | 'shinkamis-decree' | 'whisper' | 'gate-quorum' | 'ancient-accord';
+/** Backward-compatible alias for claude-flow code */
+export type ConsensusAlgorithm = CouncilProtocol;
+export interface CouncilConfig {
+    protocol: CouncilProtocol;
+    threshold: number;
+    timeoutMs: number;
+    maxRounds: number;
+    requireQuorum: boolean;
+}
+/** Backward-compatible alias — ported code uses Partial<ConsensusConfig> */
+export type ConsensusConfig = CouncilConfig;
+/** A proposal submitted to the Council (Arcanea naming) */
+export interface Petition {
+    id: string;
+    petitionerId: string;
+    value: unknown;
+    term: number;
+    timestamp: Date;
+    seals: Map<string, Seal>;
+    status: 'pending' | 'accepted' | 'rejected' | 'expired';
+}
+/**
+ * Backward-compatible proposal type for ported consensus code.
+ * Uses the original claude-flow field names (proposerId, votes).
+ */
+export interface ConsensusProposal {
+    id: string;
+    proposerId: string;
+    value: unknown;
+    term: number;
+    timestamp: Date;
+    votes: Map<string, ConsensusVote>;
+    status: 'pending' | 'accepted' | 'rejected' | 'expired';
+}
+/** A Guardian's vote on a petition (Arcanea naming) */
+export interface Seal {
+    guardianId: string;
+    approve: boolean;
+    confidence: number;
+    timestamp: Date;
+    reason?: string;
+}
+/**
+ * Backward-compatible vote type for ported consensus code.
+ * Uses the original claude-flow field name (voterId).
+ */
+export interface ConsensusVote {
+    voterId: string;
+    approve: boolean;
+    confidence: number;
+    timestamp: Date;
+    reason?: string;
+}
+/** Result of a Council deliberation (Arcanea naming) */
+export interface CouncilResult {
+    petitionId: string;
+    approved: boolean;
+    approvalRate: number;
+    participationRate: number;
+    finalValue: unknown;
+    rounds: number;
+    durationMs: number;
+}
+/**
+ * Backward-compatible result type for ported consensus code.
+ * Uses the original claude-flow field name (proposalId).
+ */
+export interface ConsensusResult {
+    proposalId: string;
+    approved: boolean;
+    approvalRate: number;
+    participationRate: number;
+    finalValue: unknown;
+    rounds: number;
+    durationMs: number;
+}
+export interface ICouncilEngine extends EventEmitter {
+    initialize(config?: CouncilConfig): Promise<void>;
+    shutdown(): Promise<void>;
+    addNode(nodeId: string, options?: {
+        isPrimary?: boolean;
+    }): void;
+    removeNode(nodeId: string): void;
+    propose(value: unknown): Promise<Petition>;
+    vote(petitionId: string, seal: Seal): Promise<void>;
+    awaitConsensus(petitionId: string): Promise<CouncilResult>;
+}
+/** Backward-compatible alias */
+export type IConsensusEngine = ICouncilEngine;
+export type TopologyType = 'mesh' | 'hierarchical' | 'centralized' | 'hybrid';
+export interface TopologyNode {
+    id: string;
+    agentId: string;
+    role: 'shinkami' | 'guardian' | 'servant' | 'equal';
+    status: 'active' | 'inactive' | 'syncing' | 'failed';
+    guardian?: GuardianName;
+    connections: string[];
+    metadata: Record<string, unknown>;
+}
+export interface GateQuorumConfig {
+    /** How many Guardians must participate (1-10) */
+    quorumSize: number;
+    /** Weight votes by Gate frequency (higher Hz = more weight) */
+    weightByFrequency: boolean;
+    /** Approval threshold as fraction of total weight (0-1) */
+    approvalThreshold: number;
+    /** How to break ties */
+    tieBreaker: 'highest-frequency' | 'element-affinity' | 'random';
+    /** Prefer Guardians of this element */
+    elementAffinity?: Element;
+    /** Timeout per vote in ms */
+    voteTimeoutMs: number;
+    /** Allow Shinkami override */
+    shinkamOverride: boolean;
+}
+export interface GateQuorumVote {
+    guardian: GuardianName;
+    frequency: number;
+    element: Element;
+    vote: 'approve' | 'reject' | 'abstain';
+    weight: number;
+    reason?: string;
+    timestamp: number;
+}
+export interface GateQuorumResult {
+    approved: boolean;
+    totalWeight: number;
+    approvalWeight: number;
+    rejectionWeight: number;
+    abstainWeight: number;
+    votes: GateQuorumVote[];
+    shinkamOverrideUsed: boolean;
+    durationMs: number;
+}
+export declare const COUNCIL_CONSTANTS: {
+    readonly DEFAULT_HEARTBEAT_INTERVAL_MS: 5000;
+    readonly DEFAULT_HEALTH_CHECK_INTERVAL_MS: 10000;
+    readonly DEFAULT_TASK_TIMEOUT_MS: 300000;
+    readonly DEFAULT_CONSENSUS_TIMEOUT_MS: 30000;
+    readonly DEFAULT_MESSAGE_TTL_MS: 60000;
+    readonly DEFAULT_MAX_AGENTS: 100;
+    readonly DEFAULT_MAX_TASKS: 1000;
+    readonly DEFAULT_CONSENSUS_THRESHOLD: 0.66;
+    readonly MAX_QUEUE_SIZE: 10000;
+    readonly MAX_RETRIES: 3;
+};
+/** Backward-compatible alias */
+export declare const SWARM_CONSTANTS: {
+    readonly DEFAULT_HEARTBEAT_INTERVAL_MS: 5000;
+    readonly DEFAULT_HEALTH_CHECK_INTERVAL_MS: 10000;
+    readonly DEFAULT_TASK_TIMEOUT_MS: 300000;
+    readonly DEFAULT_CONSENSUS_TIMEOUT_MS: 30000;
+    readonly DEFAULT_MESSAGE_TTL_MS: 60000;
+    readonly DEFAULT_MAX_AGENTS: 100;
+    readonly DEFAULT_MAX_TASKS: 1000;
+    readonly DEFAULT_CONSENSUS_THRESHOLD: 0.66;
+    readonly MAX_QUEUE_SIZE: 10000;
+    readonly MAX_RETRIES: 3;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,27 @@
+/**
+ * @arcanea/council — Type Definitions
+ *
+ * Rebranded from claude-flow swarm types to Arcanea Council terminology.
+ * Consensus algorithms become Council protocols. Swarm topology becomes
+ * Guardian Council formation. Queen becomes Shinkami.
+ *
+ * Backward-compatible interfaces (ConsensusProposal, ConsensusVote,
+ * ConsensusResult) preserve the original claude-flow field names so
+ * ported consensus implementations work without modification.
+ */
+// ── Constants ────────────────────────────────────────────────
+export const COUNCIL_CONSTANTS = {
+    DEFAULT_HEARTBEAT_INTERVAL_MS: 5000,
+    DEFAULT_HEALTH_CHECK_INTERVAL_MS: 10000,
+    DEFAULT_TASK_TIMEOUT_MS: 300000,
+    DEFAULT_CONSENSUS_TIMEOUT_MS: 30000,
+    DEFAULT_MESSAGE_TTL_MS: 60000,
+    DEFAULT_MAX_AGENTS: 100,
+    DEFAULT_MAX_TASKS: 1000,
+    DEFAULT_CONSENSUS_THRESHOLD: 0.66,
+    MAX_QUEUE_SIZE: 10000,
+    MAX_RETRIES: 3,
+};
+/** Backward-compatible alias */
+export const SWARM_CONSTANTS = COUNCIL_CONSTANTS;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAwLH,gEAAgE;AAEhE,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,6BAA6B,EAAE,IAAI;IACnC,gCAAgC,EAAE,KAAK;IACvC,uBAAuB,EAAE,MAAM;IAC/B,4BAA4B,EAAE,KAAK;IACnC,sBAAsB,EAAE,KAAK;IAC7B,kBAAkB,EAAE,GAAG;IACvB,iBAAiB,EAAE,IAAI;IACvB,2BAA2B,EAAE,IAAI;IACjC,cAAc,EAAE,KAAK;IACrB,WAAW,EAAE,CAAC;CACN,CAAC;AAEX,gCAAgC;AAChC,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@arcanea/council",
+  "version": "0.1.0",
+  "description": "Guardian Council consensus mechanics — Byzantine, Raft, Gossip, and Gate Quorum protocols for the Ten Guardians",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./consensus": {
+      "types": "./dist/consensus/index.d.ts",
+      "import": "./dist/consensus/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test tests/council.test.mjs"
+  },
+  "keywords": [
+    "arcanea",
+    "council",
+    "consensus",
+    "guardian",
+    "byzantine",
+    "raft",
+    "gossip"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@arcanea/guardian-memory": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.5.0"
+  }
+}