Policies

Pluggable consensus policy registry with 9 built-in resolution strategies and support for custom policies.

Overview

@consensus-tools/policies provides a pluggable policy registry on top of the 9 built-in resolution strategies from core. Use it when you need to swap consensus policies at runtime or register custom resolution logic.

Installation

pnpm add @consensus-tools/policies

Quick start

import { createPolicyRegistry, createRegistryResolver } from "@consensus-tools/policies";

const registry = createPolicyRegistry(); // pre-loaded with all 9 policies
const resolver = createRegistryResolver(registry);

// resolver dispatches based on job.consensusPolicy.type
const result = resolver({ job, submissions, votes, reputation: (agent) => 1 });
console.log(result.winners, result.consensusTrace);

API reference

createPolicyRegistry()

Returns a Map<ConsensusPolicyType, PolicyResolver> pre-loaded with all 9 built-in policies.

function createPolicyRegistry(): Map<ConsensusPolicyType, PolicyResolver>;

createRegistryResolver()

Returns a PolicyResolver that dispatches to the correct policy based on job.consensusPolicy.type.

function createRegistryResolver(
  registry?: Map<ConsensusPolicyType, PolicyResolver>
): PolicyResolver;

If no registry is provided, a default one is created internally.

Individual policy functions

Each policy is exported as a standalone function:

import { approvalVote, majorityVote, topKSplit } from "@consensus-tools/policies";

const result = approvalVote({ job, submissions, votes, reputation });

Built-in policies

Policy	Type Key	How it resolves
`firstSubmissionWins`	`FIRST_SUBMISSION_WINS`	Earliest valid submission wins
`highestConfidenceSingle`	`HIGHEST_CONFIDENCE_SINGLE`	Submission with highest confidence score (above `minConfidence`)
`approvalVote`	`APPROVAL_VOTE`	Quorum-based voting with configurable weight mode, settlement, tie-breaking
`majorityVote`	`MAJORITY_VOTE`	Simple majority -- each vote counts equally
`weightedVoteSimple`	`WEIGHTED_VOTE_SIMPLE`	Votes weighted by explicit `weight` field
`weightedReputation`	`WEIGHTED_REPUTATION`	Votes weighted by agent reputation score
`ownerPick`	`OWNER_PICK`	Job creator manually selects the winner
`trustedArbiter`	`TRUSTED_ARBITER`	Designated arbiter agent decides
`topKSplit`	`TOP_K_SPLIT`	Reward split among top K submissions (by confidence or score)

Examples

Register a custom policy

import { createPolicyRegistry, createRegistryResolver } from "@consensus-tools/policies";

const registry = createPolicyRegistry();
registry.set("MY_CUSTOM_POLICY", (input) => {
  const best = input.submissions.sort((a, b) => b.confidence - a.confidence)[0];
  return {
    winners: best ? [best.agentId] : [],
    winningSubmissionIds: best ? [best.id] : [],
    consensusTrace: { policy: "MY_CUSTOM_POLICY" },
    finalArtifact: best?.artifacts ?? null,
  };
});

const resolver = createRegistryResolver(registry);

ℹ

Custom policy return shape

Custom policies must return an object with winners, winningSubmissionIds, consensusTrace, and finalArtifact fields to match the built-in resolver interface.

core -- Provides the underlying policy resolver functions that this package wraps
workflows -- Uses policies during job resolution within workflow steps

Previous←core Nextworkflows→