The Semantic System Graph

Software systems have plenty of artifacts: code, schemas, APIs, interfaces, workflows, infrastructure, tests, documentation, and telemetry. The missing object is a durable account of how their meaning fits together.

Cohesive calls the compiler's connected, versioned semantic state a semantic system graph. The graph links domain meaning to system structure, operational requirements, infrastructure capabilities, and the concrete artifacts that run.

The distinctions matter. An entity is not a table. A transition is not an endpoint. An effect is not a message. A service is not a deployment. The graph relates these objects without collapsing them into one model.

A Change That Does Not Fit In A File

Consider a small product request:

Let a support agent refund an order.

Implementation can begin quickly. Add a route, call the payment provider, update a record, expose a button, and give an agent a tool. The request still leaves the consequential questions unanswered.

• Which captures are refundable, and how is the remaining amount calculated?
• Who may request, approve, authorize, and execute the refund?
• What happens when two requests race?
• When does the payment obligation become durable?
• How are timeouts, retries, duplicates, and settlement represented?
• Which facts are authoritative for recovery and audit?

The answers live across validation code, database constraints, payment adapters, approval workflows, interfaces, policy, and team knowledge. Search can find many of those artifacts. It cannot decide which interpretation the organization accepts.

The real change is a change in system meaning.

Readable Source, Connected Graph

People and agents edit modular Cohesive artifacts. Those files define entities, relations, transitions, processes, policy, operational requirements, bindings, and other semantic objects. They remain readable, reviewable, versioned source.

A deterministic compiler parses the artifacts, resolves stable identities and dependencies, applies versioned language rules, and accumulates the graph. The graph can be persisted for incremental analysis, semantic diffing, provenance queries, and selective regeneration. It remains derived state.

Deleting the graph and rebuilding from the same source, compiler version, configuration, and declared inputs produces an equivalent result and the same diagnostics.

Language models stay outside that boundary. They help discover structure, propose source edits, and explain results. Runtime observations enter as evidence with their own provenance. Evidence can support or contradict a claim without silently becoming intent.

The Graph Keeps Different Concerns Connected

The semantic system graph is connected but not homogeneous. It keeps several kinds of meaning distinct:

Typed mappings connect the layers. A transition projects to an API operation without becoming an endpoint. A message carries an effect without defining it. A transaction realizes a commit boundary without becoming the domain rule.

The system graph mediates between meaning and realization. It composes semantic objects for one system, scopes authority and requirements, and leaves realization choices open. A process may run on a workflow engine, an actor, a database-backed process manager, or a generated worker when the selected mechanism satisfies the same requirements.

Change Appears As A Semantic Delta

Stable identities let system meaning outlive filenames, classes, endpoints, and deployments. CommitRefund remains the same subject when its handler moves or a REST operation becomes a workflow signal.

Let $A_t$ be the accepted artifact set, $V$ the compiler and language version, and $C$ the declared configuration. The compiler derives graph state $G_t$:

A source change produces a new graph and a semantic delta:

The delta reports changes in meaning, not only text. It shows that a transition became legal, an invariant changed, authority moved, a process gained an approval step, or an effect acquired a recovery requirement.

Each claim retains several independent properties. Lifecycle records whether it is proposed, accepted, or deprecated. Provenance records whether it was authored, inferred, derived, or observed. Authority records who may accept it at which boundary. Assurance records whether its support is verified, derived, test-backed, declared, assumed, or opaque.

This also improves merge behavior. Git merges source text. Cohesive rebuilds the graph and reports contradictory definitions, incompatible transitions, or unsupported realizations. The tooling surfaces semantic conflict without pretending every conflict has an automatic resolution.

The Refund Change In The Graph

The refund definitions include an Order, a Refund, captured and previously refunded amounts, an approval process, and a payment effect. Together they state the central invariant:

CommittedRefunds(o) means refunds whose local payment obligations are authorized and durable. It does not mean that the provider has settled them.

The same definitions project into an API operation, support action, agent tool, approval task, persistence artifacts, and runtime traces. Each projection states what it includes, hides, weakens, or cannot safely edit. Shared semantic identities keep those artifacts connected.

Shared Meaning, Different Consumers

The graph supplies different context for different work. Development agents receive relevant definitions and dependencies. Interaction agents receive declared observations, actions, processes, policy, and authority. Product, design, security, operations, and data teams each use a perspective shaped by the decisions they make and the work they own.

The graph is not merely an architecture diagram, documentation set, or generic knowledge graph. Its definitions participate in compilation, validation, capability matching, generation, and conformance. It also is not one universal formal specification. Specialized analyses use projections that preserve the details required for a particular question.

Without a durable graph, each change begins by reconstructing meaning from organizational residue. With accepted semantic source, new intent becomes a reviewable delta over known identities, constraints, authorities, and boundaries. Realizations remain concrete software that runs, fails, and recovers. The graph gives that software something precise to mean.