The Semantic System Graph

Software systems do not suffer from a shortage of artifacts. They have code, schemas, APIs, interfaces, workflows, infrastructure, tests, documentation, and telemetry. What they lack is a durable object that says how the meaning distributed across those artifacts fits together.

Cohesive calls the complete, connected, versioned model a semantic system graph. It connects a semantic graph, a system graph, an infrastructure projection, and one or more realization graphs. In this article, system graph refers specifically to the mediating realm that composes domain meaning into a particular system and states its authority, responsibilities, and boundaries.

The distinction matters. An entity is not a table. A transition is not an endpoint. An effect is not a message. A service is not necessarily a deployment. Those things can be related, generated, and checked against one another without being collapsed into the same object.

A Change That Does Not Fit in a File

Consider a seemingly small request:

Let a support agent refund an order.

It sounds like an API operation and a button. Implementation can begin quickly: add a route, call a payment provider, update a record, expose the action in the support interface, and give an agent a tool with the right parameters.

But the request leaves almost every consequential question open.

• Which orders and payment captures are refundable?
• How is the remaining refundable amount calculated across earlier refunds?
• Who may request, approve, commit, and execute the refund?
• Can an AI agent commit the change or only propose it for approval?
• What happens when two refund requests race?
• When does the external payment obligation come into existence?
• How is a timeout distinguished from a failed or duplicated payment call?
• Which record is authoritative for recovery and audit?
• What should the API, UI, workflow, and agent observe at each stage?

The answers are unlikely to live together. Some are encoded in validation code, some in database constraints, some in a payment adapter, some in an approval workflow, and some only in the judgment of the team operating the system. A repository search can locate many of the artifacts. It cannot by itself settle which interpretation the organization is willing to treat as authoritative.

The real change is not a set of files. It is a change in system meaning.

The Canonical Graph Stack

Code executes, but schemas, APIs, interfaces, infrastructure, tests, and runtime traces also reveal system commitments. No one artifact models the whole. The system exists through their correspondences: a button invokes an operation, the operation requests a transition, the transition preserves an invariant and establishes an effect, and a selected runtime attempts that effect under stated conditions.

When those correspondences remain implicit, people and agents reconstruct a provisional model from conventions, filenames, call graphs, tickets, and observations. A canonical system-graph definition makes the meaning-bearing objects and their mappings explicit enough to inspect, version, validate, and attribute.

The complete semantic system graph is connected, but not homogeneous. It separates domain meaning, system-relative composition, operational qualifications, infrastructure capabilities, and concrete realization rather than placing them at one level.

The layers are connected by typed mappings rather than competing as descriptions of the same thing. Operational concerns qualify those layers and mappings at declared boundaries. The infrastructure graph projects system structure and its requirements toward public substrate capabilities, where capability evidence can be evaluated before a vendor- or environment-specific realization is selected.

The system graph is the stack's mediating layer. It composes semantic subjects into entity, observer, relation, transition, service, and process models; assigns authority and responsibility at boundaries; scopes invariants, policies, and effects; and exposes realization-neutral requirements. The separation keeps architectural choice open: the same process graph may be realized by a workflow engine, an actor, a database-backed process manager, or a generated worker topology when each candidate preserves the required semantics.

Refund Across the Stack

The refund change from the opening already spans this structure:

The later refund coordination diagram expands this compact mapping into its observations, authority, commit, and effect relationships.

Cross-Realm Mappings Carry Meaning

The stack is held together by cross-realm relations. These are typed correspondences, not claims of identity.

These mappings prevent category errors without erasing architectural choice. A transition may project to an endpoint without becoming one; a message may carry an effect without defining it; a deployment may realize a service without being identical to it. A requirement may admit several realizations—or none when capability evidence is insufficient.

Versioned Claims and Semantic Deltas

A system definition is useful only if its meaning survives the ordinary motion of software development.

Durable means semantic identities outlive filenames, classes, endpoints, and deployment arrangements. CommitRefund remains referable when its handler moves, when a REST operation becomes a workflow signal, or when a database schema is replaced.

Accumulative means accepted decisions become reusable context. A new feature extends or revises existing meaning rather than beginning with another round of repository archaeology. The reason for an approval boundary, the scope of an invariant, and the authority behind a transition remain connected to the subjects they govern.

Versioned means the graph records semantic evolution, not only the latest snapshot. Let $\mathcal{M}_t$ be the accepted modeled system and $\Delta_t$ a proposed semantic change:

The delta becomes authoritative only after its relevant constraints, compatibility rules, and review obligations have been satisfied. A semantic diff can then say more than which files changed. It can say that a transition became legal, an invariant was strengthened, authority moved, a process gained an approval boundary, or an effect acquired an idempotency requirement.

A proposed refund delta, $\Delta_{\mathrm{refund}}$, can make those changes concrete without committing to a particular authoring syntax:

The delta changes accepted meaning while leaving realization choices open. An outbox, a durable workflow, or another mechanism may later realize the payment obligation if it satisfies the attached requirements.

Versioning also makes long-lived execution explicit. A process started under one graph revision may continue while a newer revision is deployed. Stored events, snapshots, API clients, and agent capability descriptions may outlive the code that created them. Compatibility is therefore a relationship between semantic revisions and their coexisting realizations, not merely a schema decoder accepting old bytes.

Versioning the graph also means versioning its claims. An accumulative graph cannot treat every assertion as equally true. It has to remember not only what was claimed, but where the claim came from, where it is in its lifecycle, what the available evidence says, and who may make it authoritative. These are independent dimensions: a claim can simultaneously be inferred from code, proposed as intent, and contradicted by a runtime observation.

Authority is boundary-relative. Code and runtime traces can provide evidence without authority to redefine intent. Learned or probabilistic tools can infer candidate structures, contradictions, and semantic deltas, but confidence does not grant authority; inferred meaning still needs an explicit path to acceptance.

This is where the comprehension bottleneck and the intent-specification bottleneck meet.

Comprehension is retrospective and epistemic: what does the system mean now, and why? Intent specification is prospective and normative: what should the system mean after this change? Implementation realizes the transition between the two.

Because accepted intent accumulates, comprehension begins from a known model and specification becomes a proposed delta over existing identities, constraints, authorities, and boundaries. Review can focus on the semantic change rather than reconstructing it from a large implementation diff.

Detailed Refund Coordination

Return to the refund request. A useful semantic slice might declare an Order, a Refund, captured and previously refunded amounts, a refund-request process, and a payment effect. It can state the central invariant:

Here, CommittedRefunds(o) means refunds whose local payment obligations have been authorized and committed. It does not mean that funds have already moved or that the payment provider has settled the refund.

The lifecycle keeps several facts distinct:

• Refund proposed: an agent or person has requested a candidate action.
• Refund authorized / obligation committed: policy and current order state permit the refund, and the local system atomically records the refund authorization and payment obligation.
• Provider request submitted: a realization attempts the external payment effect, usually under an idempotency key.
• Provider accepted: the provider acknowledges only what its response contract says it accepted.
• Refund settled or failed: later evidence resolves the payment outcome; provider acceptance alone does not establish settlement.

In this model, CommitRefund intentionally means authorize the refund and commit its payment obligation. The system graph scopes the invariant to the authority that performs that local commit, places approval in a process graph, and exposes a separately governed agent-facing capability.

The boundary between the authoritative refund commit and the payment provider is now visible. The selected realization might use a local database transaction plus an outbox, a durable workflow, or another coordination pattern. Those choices are not interchangeable in every environment. Each has to satisfy the requirements attached to this graph slice.

The same slice can project into an API operation, a support action, a generated client, an agent tool contract, an approval task, persistence artifacts, and runtime traces. Those projections share semantic identities. They do not have to rediscover that CommitRefund means commitment of an authorized payment obligation rather than completed movement of money or a best-effort call to a payment API.

Consumers and Non-Goals

The semantic system graph gives several disciplines a shared referent without requiring identical views. Humans review semantic deltas. Compilers generate and validate artifacts. Development agents receive stable context for change; operational agents receive selected observations, actions, policies, and authority scopes. Formal tools analyze selected state spaces and constraints, while runtimes return histories and conformance evidence.

Each consumer receives a projection model appropriate to its question. An agent need not receive every internal relation, and a formal model need not include deployment details irrelevant to the property under analysis. Sharing semantic identities does not require sharing every detail.

The shared model is also easier to understand by what it is not:

The public Cohesive knowledge graph is the definition surface for the language: it defines concepts, distinctions, and relationships. An authored application's semantic system graph is an instance of that language. The definition of Authority in the knowledge graph is not the same object as the authority relation governing a particular refund transition.

From Searching for Meaning to Working From Meaning

Without a durable semantic system graph, every change begins by reconstructing a model from organizational residue. People and agents search code, documentation, tickets, telemetry, and design artifacts, infer likely correspondences, and hope the inferred model is complete enough for the task.

With an accepted semantic system graph, comprehension begins from accumulated semantic commitments. New intent can be expressed as a delta over known identities, constraints, authorities, and boundaries. Realizations can be generated or checked against explicit requirements. Runtime evidence can be attributed to the definitions it supports or contradicts.

The graph does not eliminate engineering judgment. It gives judgment a durable place to accumulate. It does not replace the realization that runs, fails, recovers, and serves users. It gives that realization something precise to mean.