Schemas

Shared Zod schemas and TypeScript types for the consensus-tools monorepo.

Overview

@consensus-tools/schemas is the contract layer for the entire monorepo. It exports Zod schemas for runtime validation and TypeScript types for compile-time safety. Every other package depends on it, and it has zero internal dependencies.

Installation

pnpm add @consensus-tools/schemas

Quick start

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 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

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: {} }

API reference

Exports reference

DomainSchemasTypes
PolicyconsensusPolicyTypeSchema, approvalVoteConfigSchema, consensusPolicyConfigSchema, slashingPolicySchemaConsensusPolicyType, ApprovalVoteConfig, ConsensusPolicyConfig, SlashingPolicy
JobjobModeSchema, jobStatusSchema, jobConstraintsSchema, escrowPolicySchema, jobSchemaJobMode, JobStatus, JobConstraints, EscrowPolicy, Job
SubmissionsubmissionStatusSchema, submissionSchemaSubmissionStatus, Submission
VotevoteTargetTypeSchema, voteSchemaVoteTargetType, Vote
ResolutionresolutionSchemaResolution
LedgerledgerEntryTypeSchema, ledgerEntrySchemaLedgerEntryType, LedgerEntry
GuardguardTypeSchema, guardDecisionSchema, guardVoteValueSchema, guardVoteSchema, weightedGuardVoteSchema, guardPolicySchema, guardEvaluateInputSchema, guardEvaluateRequestSchema, guardResultSchema, weightingModeSchema, humanApprovalRequestSchema, parseHumanApprovalYesNo (function)Matching types + VoteTally
AgentagentKindSchema, agentStatusSchema, agentSchema, agentConfigSchemaAgentKind, AgentStatus, Agent, AgentConfig
ParticipantparticipantSubjectTypeSchema, participantStatusSchema, participantSchemaParticipantSubjectType, ParticipantStatus, Participant
WorkflowworkflowStatusSchema, workflowSchema, workflowRunSchema, cronScheduleSchemaWorkflowStatus, Workflow, WorkflowRun, CronSchedule
HITLhitlModeSchema, hitlStatusSchema, hitlApprovalSchema, humanDecisionSchemaHitlMode, HitlStatus, HitlApproval, HumanDecision
TelemetrytelemetryEventTypeSchema, telemetryEventSchema, traceSpanSchemaTelemetryEventType, TelemetryEvent, TraceSpan
ConfigconsensusToolsConfigSchemaConsensusToolsConfig
StoragestorageStateSchemaStorageState
CommonclaimStatusSchema, bidSchema, assignmentSchema, auditEventSchema, diagnosticEntrySchemaClaimStatus, Bid, Assignment, AuditEvent, DiagnosticEntry
InputsjobPostInputSchema, claimInputSchema, submitInputSchema, voteInputSchema, resolveInputSchema, workflowCreateInputSchema, cronRegisterInputSchema, participantCreateInputSchema, consensusVoteInputSchemaMatching types
Policy AssignmentpolicyAssignmentSchema, consensusVoteSchemaPolicyAssignment, ConsensusVote
Resolver--ConsensusInput, ConsensusResult, PolicyResolver
Guard ConstantsBUILT_IN_GUARD_DOMAINS, GUARD_DOMAIN_DESCRIPTIONS, DEFAULT_GUARD_POLICYGuardType (re-exported)
ℹ

Zero-cost types

All Zod schemas export a matching TypeScript type via z.infer. Import with type to avoid any runtime cost when you only need compile-time checking.

Related

Previous←OverviewNextsecrets→