Core Types
The @zakardo/core package exports branded types, enums, and utility types used throughout the Zakardo framework.
Branded IDs
Section titled “Branded IDs”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:
EffectClass
Section titled “EffectClass”What side effects a capability produces:
import { EffectClass } from '@zakardo/core';
EffectClass.READ // Only reads dataEffectClass.WRITE_INTERNAL // Mutates data within the appEffectClass.WRITE_EXTERNAL // Side effects outside system boundaryEffectClass.DESTRUCTIVE // Irreversible operationsSeverity 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'Boundary
Section titled “Boundary”Where a capability executes:
import { Boundary } from '@zakardo/core';
Boundary.LOCAL // Within the server processBoundary.REMOTE // External service (HTTP/gRPC)Boundary.USER_ENV // User's browser or deviceExecutionMode
Section titled “ExecutionMode”How a plan is executed:
import { ExecutionMode } from '@zakardo/core';
ExecutionMode.SIMULATED // No capabilities execute — simulated I/OExecutionMode.DRY_RUN // READs execute, writes logged but not committedExecutionMode.LIVE // Full execution with real side effectsThere is also a TRAINING mode used by the Training System.
LifecycleState
Section titled “LifecycleState”The trust lifecycle of a plan:
import { LifecycleState } from '@zakardo/core';
LifecycleState.CANDIDATE // Newly generated, unprovenLifecycleState.SHADOW // Being tested in parallelLifecycleState.PROMOTED // Proven reliable, used for matchingLifecycleState.DEPRECATED // Replaced, no longer used for new intentsLifecycleState.QUARANTINED // Failed reliability thresholdsSchemaKind
Section titled “SchemaKind”Classification of JSON Schemas in the x-zakardo extension:
import { SchemaKind } from '@zakardo/core';
SchemaKind.CAPABILITY_INPUT // Input schema for a capabilitySchemaKind.CAPABILITY_OUTPUT // Output schema for a capabilitySchemaKind.INTERACTION_RESPONSE // Schema for user interaction responsesSchemaKind.CONTEXT_DATA // Schema for execution context dataOther Enums
Section titled “Other Enums”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'The Result Pattern
Section titled “The Result Pattern”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 resultsconst success = ok('value'); // { ok: true, value: 'value' }
// Create error resultsconst failure = err(new Error('x')); // { ok: false, error: Error }
// Pattern matchingfunction 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.
JSON Schema Type
Section titled “JSON Schema Type”import type { JsonSchema, ZakardoExtension } from '@zakardo/core';
// Loosely typed JSON Schema documentconst schema: JsonSchema = { type: 'object', properties: { name: { type: 'string' } }, 'x-zakardo': { kind: 'capability-input', version: '1.0.0' } satisfies ZakardoExtension,};Further Reading
Section titled “Further Reading”- Type System Specification — full JSON Schema extension spec
- Capabilities — how types are used in capability definitions