@holonograph/types-public

The public wire-format types and schemas for a Holonograph lens.

A Holonograph lens turns every LLM call into a longitudinal, gradeable record. This package is the shared type contract for the messages that cross the wire to and from the lens: the request you send, the evaluation event that gets stored, the substrate snapshot pinned into it, the surface contract you register, and the read shapes the lens returns. Every field is a plain TypeScript type backed by a runtime zod schema, so you can both type your integration and validate payloads against the same shapes the lens uses.

Most applications only need @holonograph/client, which re-exports the types it needs. Reach for this package directly when you want the full wire contract — to validate payloads, to build tooling around the stored events, or to integrate a non-JS surface against a stable schema.

Install

npm install @holonograph/types-public zod

zod is a peer you already have if you validate anything; the schemas exported here are built with your zod instance so they compose with your own.

What's here

• Message shapes — the canonical request/response bodies the lens speaks.
• Substrate + snapshot — the deployment substrate tuple and the four-layer evaluation snapshot, including per-dimension results and per-dimension judge identity.
• Surface contract — the operator-declared contract of surfaces and their grading dimensions.
• Read shapes — the wire shapes for the lens's longitudinal reads (attention, reach, verdict reliability, facet coverage, and more).

Usage

import {
  DimensionResultSchema,
  type DimensionResult,
  type EvaluationEvent,
} from '@holonograph/types-public';

// Type your integration against the wire contract.
function summarize(event: EvaluationEvent): string {
  return event.surfaceId;
}

// Or validate a payload at the boundary with the same schema the lens uses.
const parsed: DimensionResult = DimensionResultSchema.parse({
  dimensionId: 'is_actionable',
  passed: true,
  expected: 'a concrete next step',
  actual: 'offered to open a replacement order',
});

Schemas .parse() and .extend() like any zod schema, so you can layer your own refinements on top of the wire contract.

License

MIT