Graph extensions: .d.ts codegen from GraphExtension document for plugin / install-time use

[pdlug]

Motivation

defineGraphExtension covers two distinct use cases that look identical to the runtime:

1. Agent-induced schema — the kind set is unknown until an LLM proposes it. Compile-time types are genuinely impossible. String-keyed APIs are the right answer.
2. Plugin / install-time extension — the extension document is known at publish time, just not when the core library was authored. A package ships an extension JSON; downstream consumers install it and want full typed ergonomics (store.nodes.Paper.create(...), typed query builder rows, etc.).

Today both cases collapse to the runtime ergonomics, so case (2) pays the cost of case (1) without benefit.

Proposal

A codegen path that turns a static GraphExtension document into TypeScript declarations equivalent to what defineNode / defineEdge would produce.

CLI:

pnpm typegraph generate-types ./paper-extension.json --out ./paper-extension.d.ts

Programmatic:

import { generateTypesFromExtension } from "@nicia-ai/typegraph/codegen";

const dts = generateTypesFromExtension(document, { graphTypeName: "PaperGraph" });

Output declares branded NodeDefinition / EdgeDefinition types and a merged graph type so consumers can:

import type { PaperGraph } from "./paper-extension-types";

const store = (await createStoreWithSchema(graph, backend))[0] as Store<PaperGraph>;

await store.nodes.Paper.create({ doi: "...", title: "...", year: 2024 });
//                              ^ fully typed against the extension's property shape

The runtime path is unchanged — codegen is purely a TS surface that mirrors what the runtime already merges. Plugin authors ship the JSON; consumers run codegen at install time.

Acceptance criteria

• CLI generates .d.ts from a valid GraphExtension JSON document, covering nodes, edges (including endpoint kinds), property modifiers (optional, searchable, embedding), unique constraints.
• Generated types pass pnpm typecheck when imported.
• Generated types compose with existing compile-time graphs (merged graph type).
• Documentation distinguishes the two use cases (agent-induced vs. plugin/install-time) and points each to the appropriate API.
• Example: a small plugin package in examples/ that ships an extension document + generated types, consumed by another example.

Scope

• Targets release containing Graph extensions: defineGraphExtension and store.evolve() #101.
• Codegen output is a static artifact — no runtime dependency on the codegen package.
• Out of scope: live type generation in agent-induced workflows (no, that doesn't make sense; it's case (1)).

References

• Graph extensions: defineGraphExtension and store.evolve() #101 graph extensions
• Extension document types: packages/typegraph/src/graph-extension/
• Compile-time factories the codegen output mirrors: defineNode, defineEdge, defineGraph