Foundgine.GraphQL.HotChocolate.Mutations 0.2.1

Foundgine

Foundgine is a semantic execution layer for .NET.

It takes a structured request, checks what that request means and what the caller is allowed to do, builds a provider-independent plan, and lets a provider execute that plan.

The simple idea is:

Request
  ↓
Semantic meaning
  ↓
Authorization
  ↓
Execution plan
  ↓
Provider
  ↓
Result

A request can come from GraphQL, JSON, application code, or an AI system.

The request format is not the source of truth. Foundgine's semantic model is.

Why Foundgine exists

A complex application often has several ways to ask for the same data:

GraphQL ─┐
JSON ────┤
AI ──────┤
Code ────┘
          ↓
      Foundgine
          ↓
   SQL / InMemory / ...

Without a common layer, each entry point can end up with its own rules for:

• fields
• relationships
• filters
• authorization
• pagination
• mutations
• provider-specific execution

Foundgine puts those rules in one place.

The goal is simple:

Describe the operation once, authorize it once, plan it once, and let different providers execute it.

The six words to know

Foundgine deliberately uses a small vocabulary.

The code contains more detailed types and intermediate objects, but these six words are the main mental model.

The layers

                 GraphQL / JSON / AI / Code
                            │
                            ▼
                    Semantic request
                            │
                            ▼
                         Resolve
                            │
                            ▼
                       Authorize
                            │
                            ▼
                          Plan
                            │
                 ┌──────────┴──────────┐
                 ▼                     ▼
                SQL                InMemory
                 │                     │
                 └──────────┬──────────┘
                            ▼
                         Result

Each layer has one job.

1. Abstractions

Small shared contracts and IDs.

Project:

src/Foundgine.Abstractions

2. Metadata

Describes the application model and the storage mapping.

Project:

src/Foundgine.Metadata

3. Semantics

Defines entities, fields, relationships, requests, resolution, and authorization.

Project:

src/Foundgine.Semantics

4. Planning

Turns an authorized request into a provider-independent plan.

Project:

src/Foundgine.Planning

5. Execution

Defines provider execution contracts and turns provider rows into semantic results.

Project:

src/Foundgine.Execution

6. Providers

Physical execution lives outside the semantic core.

Current providers:

src/Foundgine.Sql
src/Foundgine.InMemory

SQL is the physical database path. InMemory is deliberately small and is mainly used to prove that the plan is not SQL-specific.

7. Input adapters

Input formats stay at the edge.

src/Foundgine.Intent.Json
src/Foundgine.GraphQL.HotChocolate
src/Foundgine.GraphQL.HotChocolate.Mutations

8. AOT

Compile-time metadata support:

src/Foundgine.Aot
src/Foundgine.Aot.Generator

What Foundgine is not

Foundgine is not:

• an ORM;
• a GraphQL server;
• a database;
• an LLM framework;
• an agent framework;
• a workflow engine;
• an identity provider.

For normal object persistence, an ORM such as EF Core may still be the right tool.

Foundgine solves a different problem: turning structured application intent into an authorized executable operation.

Quick start

Requirements

• .NET 9 SDK
• Docker Engine + Docker Compose for PostgreSQL E2E tests
• Git
• Windows, Linux, or macOS

Check .NET:

dotnet --version

Check Docker:

docker version
docker compose version

Build everything

From the repository root:

dotnet restore Foundgine.sln
dotnet build Foundgine.sln --configuration Release

Run the normal test suite

dotnet test Foundgine.sln --configuration Release

Run PostgreSQL E2E tests

Start PostgreSQL 17:

docker compose -f docker-compose.postgres.yml up -d

Set the connection string.

PowerShell:

$env:FOUNDGINE_POSTGRES_CONNECTION_STRING="Host=localhost;Port=55432;Database=foundgine_e2e;Username=foundgine;Password=foundgine"

Bash:

export FOUNDGINE_POSTGRES_CONNECTION_STRING='Host=localhost;Port=55432;Database=foundgine_e2e;Username=foundgine;Password=foundgine'

Run the E2E project:

dotnet test tests/Foundgine.E2E.Tests/Foundgine.E2E.Tests.csproj \
  --configuration Release \
  --filter "FullyQualifiedName~Foundgine.E2E.Tests"

Stop PostgreSQL when finished:

docker compose -f docker-compose.postgres.yml down --volumes --remove-orphans

For a one-command Bash run, see scripts/run-postgres-e2e.sh.

For Windows PowerShell, see scripts/run-postgres-e2e.ps1.

Set up each layer

The detailed guide is:

Layer setup guide

It explains, in order:

1. Abstractions
2. Metadata
3. Semantics
4. Planning
5. Execution
6. SQL
7. InMemory
8. JSON
9. GraphQL
10. AOT
11. PostgreSQL E2E
12. PR checks

The guide also shows the smallest useful test for each layer.

The best place to learn the code

Start here:

tests/Foundgine.E2E.Tests

The Banking tests show the full read path:

input
 → semantic request
 → resolution
 → authorization
 → plan
 → SQL
 → database
 → result

The PostgreSQL PostgreSQL E2E tests extend this to real PostgreSQL and complex mutation/query flows.

Then read:

• Architecture
• Layer setup
• Testing
• PostgreSQL E2E
• Current status

PostgreSQL measurement gate

The repository has a deliberate measurement gate.

Before changing the PostgreSQL mutation compiler, run the real database tests and collect execution evidence.

The target matrix is:

batch size: 1 / 10 / 50 / 500
depth:      1 / 2 / 3

The measurement should include:

planning time
execution time

shared buffer hit/read/write
temporary read/write

WAL bytes

join type
sorts
materialization

estimated rows
actual rows
actual loops

The purpose is to optimize from PostgreSQL evidence rather than from guesses.

See:

• PostgreSQL E2E
• PostgreSQL E2E measurement gate

Pull requests

Every pull request to main runs:

Build
  ↓
All tests
  ↓
PostgreSQL 17 E2E

The PostgreSQL job starts a clean PostgreSQL 17 container, runs the E2E tests, prints database diagnostics on failure, and removes the container afterwards.

Workflow:

.github/workflows/build.yml

This means the PostgreSQL tests are optional on a developer machine but are a real CI check for pull requests.

Project map

Current proof

The active tests prove semantic modelling, resolution, authorization, provider-independent query and mutation planning, SQL/SQLite execution, a small InMemory provider, AOT metadata, JSON input, GraphQL adapters, relationship and aggregate operations, pagination, and PostgreSQL integration contracts.

The real PostgreSQL tests are the authoritative proof for the PostgreSQL execution path when FOUNDGINE_POSTGRES_CONNECTION_STRING is available.

The project does not claim universal provider support, autonomous-agent execution, workflow orchestration, or universal performance superiority.

Documentation

Start with:

1. Getting started
2. Layer setup
3. Architecture
4. Testing
5. PostgreSQL E2E
6. Current status
7. Why Foundgine
8. Provider independence
9. Security
10. Roadmap

Historical design notes are kept under docs/history.