@intentic/graph

The product-agnostic desired-state IR and its compiler: the data structure every other package is built around. A node's type is an opaque string here; the closed vocabulary lives in @intentic/resources. This is the base of the dependency graph (depended on by every other package, depends on nothing internal).

Responsibilities

• Define the serializable graph types: DesiredStateGraph, RawNode/ResourceNode, Ref, SecretRef, Readiness.
• Compile a map of RawNodes into a validated, dependency-ordered DesiredStateGraph (compile).
• Provide the primitives others compose with: typed refs between nodes, env-sourced secrets, HTTP readiness gates, and ownership stamps.
• It does not know which resource kinds exist, how to reconcile them, or how to talk to infra: those belong to resources/engine/providers.

Key files

• src/types.ts: the IR types (DesiredStateGraph, RawNode, Ref, SecretRef, Readiness).
• src/compile.ts, compile: RawNode map → graph (validates refs, fills order).
• src/topo.ts: toNodeMap, linearize (topological dependency order).
• src/ref.ts: makeRef/refKey/isRef, env (env-sourced secret), httpOk (readiness gate).
• src/stamp.ts: formatStamp/parseStamp (resource ownership stamps).
• src/serialize.ts: stable serialization of the graph.

How it fits

Foundational layer. resources constrains node types on top of it; need-resolver, state-resolver, engine, and sdk all consume its types; authors import env from here (its true source) when writing a deploy.config.ts.

Conventions & gotchas

• Refs are typed pointers to another node's outputs: never inline a downstream value; emit a Ref so ordering and resolution stay correct.
• Secrets are SecretRefs with a source (env or generated); keep them as refs, never bake plaintext into a node.
• Co-located tests in src/index.test.ts. See ARCHITECTURE.md for the full pipeline.