Install

npm install @vreko/contracts

What's Included

• Snapshot types — Snapshot, SnapshotStorage, restoration contracts
• Session types — session state, file-modification payloads, session history
• Workspace intelligence types — WorkspaceConfig, WorkspaceBinding, fragility and co-change traces (CalculationTrace, FragilityTrace)
• MCP protocol types — local-service IPC method schemas and the LocalServiceMethod union
• Error contracts — ApiError, ApiErrorCode, typed error constructors (createNotFoundError, createUnauthorizedError, etc.)
• Feature and entitlement types — tier definitions, pioneer-service contracts, feature-flag shapes
• Analytics and telemetry types — event bus types, attribution contracts, observability interfaces
• Zod validators — every public type has a co-located Zod schema for runtime validation
• LearningType enum — canonical values for Vreko intelligence learning events

Quick Start

import type { Snapshot } from "@vreko/contracts";
import { ApiError, createNotFoundError } from "@vreko/contracts/errors";
import { LocalServiceMethodSchema } from "@vreko/contracts/local-service";

// Use a type
function restoreSnapshot(snap: Snapshot) {
  console.log(snap.id, snap.workspaceId);
}

// Construct a typed API error
function lookupUser(id: string) {
  throw createNotFoundError(`User ${id} not found`);
}

// Validate an IPC method name at runtime
const result = LocalServiceMethodSchema.safeParse(rawMethod);
if (!result.success) {
  throw new ApiError("VALIDATION_ERROR", "Unknown IPC method");
}

Subpath exports are available for tree-shaking:

import { SnapshotSchema } from "@vreko/contracts/types/snapshot";
import { SessionPayloadSchema } from "@vreko/contracts/session";
import { CalculationTraceSchema } from "@vreko/contracts"; // top-level

Stability

This package follows semver:

• Patch — bug fixes and internal corrections; no API changes.
• Minor — new exports or optional schema fields added in a backwards-compatible way.
• Major — breaking changes to existing types or removed exports. Coordinate with all consumers before upgrading across a major boundary.

All Zod schemas are the source of truth; TypeScript types are derived from them via z.infer. If a schema and a type appear to disagree, the schema is correct.

License

Apache 2.0