@consensus-tools/schemas

Shared Zod schemas and TypeScript types for the consensus-tools monorepo. This package is the contract layer -- every other package depends on it and it has zero internal dependencies.

Install

pnpm add @consensus-tools/schemas

Basic Usage

Validate untrusted data at runtime using any exported Zod schema:

import { jobSchema, type Job } from "@consensus-tools/schemas";

const job: Job = jobSchema.parse(untrustedPayload); // throws ZodError on invalid data

Use the TypeScript types alone (zero runtime cost) for typed function signatures:

import type { GuardDecision, JobStatus, HitlMode } from "@consensus-tools/schemas";

function handleDecision(d: GuardDecision): void {
  if (d === "BLOCK") { /* ... */ }
}

Validate API Inputs

Each API endpoint has a matching input schema:

import { jobPostInputSchema, voteInputSchema } from "@consensus-tools/schemas";

const body = jobPostInputSchema.parse(req.body); // safe to use
const vote = voteInputSchema.parse(req.body);

Policy Configuration

import { consensusPolicyConfigSchema, type ConsensusPolicyConfig } from "@consensus-tools/schemas";

const policy: ConsensusPolicyConfig = consensusPolicyConfigSchema.parse({
  type: "APPROVAL_VOTE",
  quorum: 3,
  minMargin: 0.6,
  approvalVote: { weightMode: "reputation", settlement: "staked" },
});

Available policy types: FIRST_SUBMISSION_WINS, HIGHEST_CONFIDENCE_SINGLE, APPROVAL_VOTE, OWNER_PICK, TOP_K_SPLIT, MAJORITY_VOTE, WEIGHTED_VOTE_SIMPLE, WEIGHTED_REPUTATION, TRUSTED_ARBITER.

Guard Schemas

import { guardEvaluateInputSchema, guardResultSchema, type GuardResult } from "@consensus-tools/schemas";
import { parseHumanApprovalYesNo } from "@consensus-tools/schemas";

const input = guardEvaluateInputSchema.parse(raw);
const approved = parseHumanApprovalYesNo("yes"); // true

Exports Reference

| Domain | Schemas | Types | |---|---|---| | Policy | consensusPolicyTypeSchema, approvalVoteConfigSchema, consensusPolicyConfigSchema, slashingPolicySchema | ConsensusPolicyType, ApprovalVoteConfig, ConsensusPolicyConfig, SlashingPolicy | | Job | jobModeSchema, jobStatusSchema, jobConstraintsSchema, escrowPolicySchema, jobSchema | JobMode, JobStatus, JobConstraints, EscrowPolicy, Job | | Submission | submissionStatusSchema, submissionSchema | SubmissionStatus, Submission | | Vote | voteTargetTypeSchema, voteSchema | VoteTargetType, Vote | | Resolution | resolutionSchema | Resolution | | Ledger | ledgerEntryTypeSchema, ledgerEntrySchema | LedgerEntryType, LedgerEntry | | Guard | guardTypeSchema, guardDecisionSchema, guardVoteValueSchema, guardVoteSchema, weightedGuardVoteSchema, guardPolicySchema, guardEvaluateInputSchema, guardEvaluateRequestSchema, guardResultSchema, weightingModeSchema, humanApprovalRequestSchema, parseHumanApprovalYesNo (function) | Matching types + VoteTally | | Agent | agentKindSchema, agentStatusSchema, agentSchema, agentConfigSchema | AgentKind, AgentStatus, Agent, AgentConfig | | Participant | participantSubjectTypeSchema, participantStatusSchema, participantSchema | ParticipantSubjectType, ParticipantStatus, Participant | | Workflow | workflowStatusSchema, workflowSchema, workflowRunSchema, cronScheduleSchema | WorkflowStatus, Workflow, WorkflowRun, CronSchedule | | HITL | hitlModeSchema, hitlStatusSchema, hitlApprovalSchema, humanDecisionSchema | HitlMode, HitlStatus, HitlApproval, HumanDecision | | Telemetry | telemetryEventTypeSchema, telemetryEventSchema, traceSpanSchema | TelemetryEventType, TelemetryEvent, TraceSpan | | Config | consensusToolsConfigSchema | ConsensusToolsConfig | | Storage | storageStateSchema | StorageState | | Common | claimStatusSchema, bidSchema, assignmentSchema, auditEventSchema, diagnosticEntrySchema | ClaimStatus, Bid, Assignment, AuditEvent, DiagnosticEntry | | Inputs | jobPostInputSchema, claimInputSchema, submitInputSchema, voteInputSchema, resolveInputSchema, workflowCreateInputSchema, cronRegisterInputSchema, participantCreateInputSchema, consensusVoteInputSchema | Matching types | | Policy Assignment | policyAssignmentSchema, consensusVoteSchema | PolicyAssignment, ConsensusVote | | Resolver | -- | ConsensusInput, ConsensusResult, PolicyResolver | | Guard Constants | BUILT_IN_GUARD_DOMAINS, GUARD_DOMAIN_DESCRIPTIONS, DEFAULT_GUARD_POLICY | GuardType (re-exported) |

Guard Constants

Canonical source of truth for guard domain definitions, shared across all adapter packages:

import {
  BUILT_IN_GUARD_DOMAINS,
  GUARD_DOMAIN_DESCRIPTIONS,
  DEFAULT_GUARD_POLICY,
} from "@consensus-tools/schemas";

BUILT_IN_GUARD_DOMAINS;
// => ["send_email", "code_merge", "publish", "support_reply", "agent_action", "deployment", "permission_escalation"]

GUARD_DOMAIN_DESCRIPTIONS["agent_action"];
// => "Evaluate autonomous agent action — blocks irreversible actions, flags external side effects"

DEFAULT_GUARD_POLICY;
// => { policyId: "default-guard", version: "v1", quorum: 0.7, riskThreshold: 0.7, hitlRequiredAboveRisk: 0.7, options: {} }

Links

consensus-tools on GitHub