Zod v4 + Schema Metadata + Reducer-Based State Compilation
This is a single, self-contained learning note.
It explains why LangGraph works, how the internals are structured, and includes a minimal working implementation split into library code and user code.
TL;DR
LangGraph is not magical. It does three things:
- Attach semantics (reducers, defaults) to Zod schemas via metadata
- Compile schemas into per-field runtime “channels”
- Execute nodes by applying reducers to merge updates
Everything else is ergonomics.
Mental Model (keep this)
| Layer | Responsibility |
|---|---|
| Zod schema | State shape |
| Schema meta | Merge semantics |
| Registry | Bind shape → semantics |
| Compiler | Shape + semantics → execution plan |
| Runtime | Execute nodes + apply reducers |
Why metadata exists
Zod answers validation questions.
It does not answer state-merge questions.
Examples Zod cannot answer:
- “Append or overwrite?”
- “Replace by id or always push?”
- “What’s the default value?”
So LangGraph keeps Zod pure and adds out-of-band metadata.
Why metadata is attached to schema instances
This must be legal:
const ChatSchema = z.object({messages: chatMessagesSchema, // merge-by-id
})const AuditSchema = z.object({messages: auditMessagesSchema, // append-only
})
Same key name, different semantics.
Hence:
WeakMap<ZodSchemaInstance, SchemaMeta>
```### Design patterns involvedCompiler pattern: schema → runtime planStrategy pattern: per-field reducerDecorator / Annotation: schema metadataTypeclass-like dispatch: “for this type, here’s how it merges”### Minimal ImplementationEverything below is runnable TypeScript.lib/state-graph.ts (library code)```ts
import { z } from 'zod/v4'
import { randomUUID } from 'node:crypto'/* ---------- core types ---------- */export type Reducer<TValue, TUpdate> = (left: TValue, right: TUpdate) => TValueexport type SchemaMeta<TValue, TUpdate = TValue> = {default?: () => TValuereducer?: {fn: Reducer<TValue, TUpdate>}
}export type Channel<TValue, TUpdate> = {default: () => TValuereducer: Reducer<TValue, TUpdate>
}export type Node<TState> = (state: TState) => Promise<Partial<TState>> | Partial<TState>/* ---------- metadata registry ---------- */
/*** Matches Zod v4 `.register(registry, meta)` expectations:* registry must implement `.add(schema, meta)`*/
export class MetaRegistry {private map = new WeakMap<object, SchemaMeta<any, any>>()add<TValue, TUpdate>(schema: object, meta: SchemaMeta<TValue, TUpdate>) {this.map.set(schema, meta)return schema}get(schema: object) {return this.map.get(schema)}
}/* ---------- compiler ---------- */
/*** Compile Zod object schema into runtime channels.* Each channel knows:* - how to initialize default state* - how to merge updates (reducer strategy)*/
export function compileChannels(schema: z.ZodObject<any>, registry: MetaRegistry) {const shape = schema.shapeconst channels: Record<string, Channel<any, any>> = {}for (const [key, fieldSchema] of Object.entries(shape)) {const meta = registry.get(fieldSchema as any)if (meta?.reducer) {channels[key] = {default: meta.default ?? (() => undefined),reducer: meta.reducer.fn,}} else {// last-write-wins fallbackchannels[key] = {default: meta?.default ?? (() => undefined),reducer: (_left: any, right: any) => right,}}}return channels
}/* ---------- runtime ---------- */
/*** Execute nodes sequentially.* State updates are merged via compiled reducers.*/
export async function runGraph<TState extends Record<string, any>>(schema: z.ZodObject<any>,registry: MetaRegistry,nodes: Array<Node<TState>>,initial: TState
) {const channels = compileChannels(schema, registry)let state: TState = { ...initial }// initialize defaultsfor (const [key, ch] of Object.entries(channels)) {if (state[key as keyof TState] === undefined) {state[key as keyof TState] = ch.default()}}// execute nodesfor (const node of nodes) {const update = await node(state)for (const [key, value] of Object.entries(update)) {const ch = channels[key]if (!ch) continuestate[key as keyof TState] = ch.reducer(state[key], value)}}return state
}/* ---------- built-in reducer preset ---------- */export type Msg = {id?: string | nullcontent: stringrole: 'human' | 'ai'
}/*** Merge-by-id messages reducer:* - ensure every message has an id* - replace existing message with same id* - append otherwise*/
export function messagesReducer(left: Msg[], right: Msg[]) {const ensureId = (m: Msg) => {if (m.id == null) m.id = randomUUID()return m}const merged = left.map(ensureId)const byId = new Map(merged.map((m, i) => [m.id as string, i]))for (const raw of right) {const m = ensureId(raw)const idx = byId.get(m.id as string)if (idx != null) {merged[idx] = m} else {byId.set(m.id as string, merged.length)merged.push(m)}}return merged
}
```demo.ts (user / application code)```ts
import { z } from 'zod/v4'
import {MetaRegistry,runGraph,messagesReducer,type Msg,type SchemaMeta,
} from './lib/state-graph'/* ---------- registry + policy ---------- */const registry = new MetaRegistry()const MessagesMeta: SchemaMeta<Msg[], Msg[]> = {default: () => [],reducer: { fn: messagesReducer },
}/* ---------- schema ---------- */
/*** Meta is attached via Zod’s native `.register()`.* Zod will call `registry.add(schema, meta)`.*/
const Schema = z.object({messages: z.array(z.object({id: z.string().optional().nullable(),content: z.string(),role: z.enum(['human', 'ai']),})).register(registry, MessagesMeta),
})type State = z.infer<typeof Schema>/* ---------- nodes ---------- */const node1 = () => ({messages: [{ role: 'human', content: 'Hello, how are you?' }],
})const node2 = () => ({messages: [{ role: 'ai', content: "I'm good, thank you!" }],
})const node3 = () => ({messages: [{ role: 'human', id: 'm-123', content: 'Corrected message' }],
})const node4 = () => ({messages: [{ role: 'ai', id: 'm-456', content: 'Corrected AI message' }],
})/* ---------- run ---------- */const result = await runGraph<State>(Schema, registry, [node1, node2, node3, node4], {messages: [{ role: 'human', id: 'm-123', content: 'Initial human message' },{ role: 'ai', id: 'm-456', content: 'Initial AI message' },],
})console.log(result)
```###Why this matches LangGraph exactlyUses Zod v4 native .register()Registry implements .add() like LangGraph’sReducers are field-level strategiesRuntime is reducer-agnosticMessages behavior is opt-in policy, not hard-coded### The Big InsightLangGraph is a deterministic state-machine compiler.
LLM calls are just nodes.
Reducers are the real power.Once you see that, nothing feels magical again.### Where to go nextParallel branches → associative reducersStreaming → partial updates as reducer inputsCRDT-style reducersVisualizing compiled channelsAt that point, you’re not using LangGraph.You’re designing execution semantics.