Skip to content

Core Types

The @zakardo/core package exports branded types, enums, and utility types used throughout the Zakardo framework.

Zakardo uses branded types for identifiers to prevent accidental mixing:

import { createPlanId, createExecutionId, createValidationId } from '@zakardo/core';
import type { PlanId, ExecutionId, ValidationId } from '@zakardo/core';
const planId: PlanId = createPlanId(crypto.randomUUID());
const execId: ExecutionId = createExecutionId(crypto.randomUUID());
const valId: ValidationId = createValidationId(crypto.randomUUID());
// Type error: cannot assign PlanId to ExecutionId
// const wrong: ExecutionId = planId;

Zakardo enums use the const object + type extraction pattern for runtime values with type safety:

What side effects a capability produces:

import { EffectClass } from '@zakardo/core';
EffectClass.READ // Only reads data
EffectClass.WRITE_INTERNAL // Mutates data within the app
EffectClass.WRITE_EXTERNAL // Side effects outside system boundary
EffectClass.DESTRUCTIVE // Irreversible operations

Severity ordering: READ < WRITE_INTERNAL < WRITE_EXTERNAL < DESTRUCTIVE

import { compareSeverity, maxSeverity, EFFECT_CLASS_SEVERITY } from '@zakardo/core';
compareSeverity('READ', 'DESTRUCTIVE'); // -3 (READ is less severe)
maxSeverity('READ', 'WRITE_EXTERNAL'); // 'WRITE_EXTERNAL'

Where a capability executes:

import { Boundary } from '@zakardo/core';
Boundary.LOCAL // Within the server process
Boundary.REMOTE // External service (HTTP/gRPC)
Boundary.USER_ENV // User's browser or device

How a plan is executed:

import { ExecutionMode } from '@zakardo/core';
ExecutionMode.SIMULATED // No capabilities execute — simulated I/O
ExecutionMode.DRY_RUN // READs execute, writes logged but not committed
ExecutionMode.LIVE // Full execution with real side effects

There is also a TRAINING mode used by the Training System.

The trust lifecycle of a plan:

import { LifecycleState } from '@zakardo/core';
LifecycleState.CANDIDATE // Newly generated, unproven
LifecycleState.SHADOW // Being tested in parallel
LifecycleState.PROMOTED // Proven reliable, used for matching
LifecycleState.DEPRECATED // Replaced, no longer used for new intents
LifecycleState.QUARANTINED // Failed reliability thresholds

Classification of JSON Schemas in the x-zakardo extension:

import { SchemaKind } from '@zakardo/core';
SchemaKind.CAPABILITY_INPUT // Input schema for a capability
SchemaKind.CAPABILITY_OUTPUT // Output schema for a capability
SchemaKind.INTERACTION_RESPONSE // Schema for user interaction responses
SchemaKind.CONTEXT_DATA // Schema for execution context data
import { TraceMode, InteractionType, ErrorCategory } from '@zakardo/core';
// TraceMode: 'full' | 'hash' | 'omit'
// InteractionType: 'SELECT' | 'COMPARE' | 'REVIEW' | 'INPUT' | 'CONFIRM'
// ErrorCategory: 'VALIDATION_ERROR' | 'BUSINESS_ERROR' | 'TRANSIENT_ERROR' | 'INFRASTRUCTURE_ERROR' | 'TIMEOUT'

Operations that can fail return a Result<T, E> instead of throwing:

import { ok, err } from '@zakardo/core';
import type { Result } from '@zakardo/core';
type MyResult = Result<string, Error>;
// Create success results
const success = ok('value'); // { ok: true, value: 'value' }
// Create error results
const failure = err(new Error('x')); // { ok: false, error: Error }
// Pattern matching
function handle(result: MyResult) {
if (result.ok) {
console.log(result.value); // TypeScript narrows to string
} else {
console.error(result.error); // TypeScript narrows to Error
}
}

throw is reserved for programming errors (bugs). User-facing failures return Result.

import type { JsonSchema, ZakardoExtension } from '@zakardo/core';
// Loosely typed JSON Schema document
const schema: JsonSchema = {
type: 'object',
properties: { name: { type: 'string' } },
'x-zakardo': { kind: 'capability-input', version: '1.0.0' } satisfies ZakardoExtension,
};