The Workspace Model Comes First. The Graph Comes Next.

Graphs are a natural fit for software systems. Projects depend on packages. Endpoints are implemented by controllers. Services use databases. Deployments run images. Documents describe decisions.

That does not make the graph the source of truth.

Workspai separates two responsibilities:

Workspace Model = canonical meaning
Workspace Graph = relationship-oriented representation

This boundary keeps Workspace Intelligence portable, testable, and useful outside a single database or AI tool.

Begin with sources, not nodes

A workspace can be observed through several provider domains:

• workspace and project foundations;
• source structure and package manifests;
• OpenAPI, GraphQL, Protobuf, and AsyncAPI interfaces;
• Docker, Compose, Kubernetes, Terraform, and CI definitions;
• Markdown, ADRs, tests, and CODEOWNERS;
• Workspai contracts and generated evidence.

Providers produce facts and proofs. They do not each get to invent a private meaning for the workspace.

A simplified fact might say:

subject: api-service
predicate: exposes
object: GET /users
proof:
  provider: openapi
  artifact: openapi.yaml
  pointer: paths./users.get

Identity resolution can then decide whether two providers refer to the same service, API, project, or file. Reconciliation can preserve conflicting or ambiguous observations instead of silently promoting them to truth.

The normalized result becomes the Workspace Model.

Why the model is canonical

Not every useful property is an edge. A project can have a runtime, profile, version, location, state, and freshness metadata. These values need stable schema semantics whether a consumer reads the canonical JSON, queries a graph, or receives a bounded agent context.

A canonical model provides:

• versioned entity and relationship semantics;
• stable identities;
• provenance and freshness;
• deterministic serialization;
• validation independent of presentation;
• a stable revision to which derived outputs can be bound.

This makes the model an open contract rather than a renderer detail.

Derive the graph

Once the model and project topology exist, Workspai derives a proof-backed Knowledge Graph:

(workspace)-[:CONTAINS]->(project)
(project)-[:DEPENDS_ON]->(package)
(api)-[:IMPLEMENTED_BY]->(controller)
(service)-[:DEPLOYS]->(deployment)

The relationship is only the beginning. Proof records can identify the provider, source artifact, pointer or line, content hash, freshness, derivation, trust, and confidence.

That is what makes the graph more than a visualization. The current CLI uses it for:

• bounded search;
• entity and proof retrieval;
• relationship paths;
• change overlays;
• agent context and agent synchronization;
• MCP queries;
• contract graph output;
• two- and three-dimensional visualization inputs.

The graph remains bound to an exact source-model revision. Context and MCP consumers can reject it when its model hash is no longer current.

Current CLI path

From a Workspai workspace:

npx workspai workspace model --write --json

The command publishes these artifacts atomically:

.workspai/reports/workspace-model.json
.workspai/reports/workspace-knowledge-graph.json

For repeated runs, Workspai also exposes model caching and incremental rebuilding:

npx workspai workspace model \
  --write \
  --cache \
  --incremental \
  --json

Incremental behavior changes the work required to rebuild the model. It must not change the output contract or permit semantically stale relationships. Replacing the immutable graph object is the current query-index invalidation boundary.

Interchange is a projection

The current graph surface can emit:

npx workspai workspace graph mermaid
npx workspai workspace graph dot
npx workspai workspace graph jsonld --output workspace-graph.jsonld
npx workspai workspace graph graphml --output workspace-graph.graphml
npx workspai workspace graph gexf --output workspace-graph.gexf

Mermaid and DOT serve documentation and diagrams. JSON-LD, GraphML, and GEXF serve semantic and graph-analysis tools. The canonical graph JSON can feed IDE and visualization layers.

These are deterministic projections of one graph revision. They do not create alternative workspace truths.

What a standalone graph engine should own

A reusable graph engine can own:

• projection from model entities and relationships;
• proof-path preservation;
• query and traversal primitives;
• storage adapters;
• incremental invalidation and query-cache semantics;
• change overlays;
• export and visualization projections.

It should not own:

• the canonical Workspace Model schema;
• product-specific release policy;
• an LLM provider;
• one mandatory graph database.

Some of these package boundaries describe the direction of the unpublished standalone graph package. They are not claims that every adapter already ships in the current CLI.

What this architecture buys us

The same model can currently serve:

Workspace Model
├── canonical model JSON
├── proof-backed graph JSON
├── Mermaid and DOT
├── JSON-LD, GraphML, and GEXF
├── MCP resources and tools
├── bounded agent context
└── CI and IDE consumers

None of them gets to silently redefine the system.

The graph may be the most powerful representation of a workspace. It still comes second, because a representation should not own the meaning it represents.