Foundgine - Programmable semantic execution platform for .NET

What is Foundgine

Modern applications face a structural problem: they now serve many distinct callers simultaneously. Web and mobile applications, REST and GraphQL clients, internal services, automation workflows, and increasingly AI agents all interact with the same underlying data and operations. In conventional architectures, each of these interfaces tends to grow its own authorization checks, validation rules, query translation, and data-access logic. The result is duplicated execution semantics spread across the codebase, with drift between what different callers are permitted to do and risks that escalate as the caller surface expands.

Foundgine addresses this directly. It is a programmable semantic execution platform for the .NET ecosystem that creates a controlled boundary between application callers and the data and operations they are permitted to execute. Rather than allowing each caller to implement its own validation, authorization, query translation, and data-access path, Foundgine turns structured intent into an authorized execution plan and executes that plan through a concrete provider.

The core idea is deliberately simple: callers describe what they want. Foundgine determines what is allowed, how it should execute, and which provider performs it. The runtime sits beneath higher-level systems and gives application developers a single, centralized place to define capabilities and enforce execution rules across every input surface.

The execution pipeline is explicit and observable:

Intent → Semantic Model → Resolution → Authorization → Plan → Rewrite/Optimize → Provider Compilation → Execution → Result + Evidence

It is important to be clear about what Foundgine is not. It is not an ORM replacement, not a database, not a GraphQL server, not an LLM, not an agent framework, and not an identity provider. It is an execution layer that can sit underneath those kinds of systems, providing a stable semantic boundary between what a system asks for and what an application is willing to execute — for both traditional software and intelligent agents alike.

Core Architecture & Technical Details

The architecture separates concerns across six well-defined layers: the semantic model defines application-facing capabilities; intent describes what the caller wants without binding to a physical provider; authorization determines which parts of the requested operation are permitted and can contribute predicates or constraints; the planner builds a provider-independent representation; rewriting and optimization transforms the plan while preserving semantics and authorization constraints; and the provider compiles and executes the plan against a concrete backend.

This separation enables a multi-caller execution model. REST/API, GraphQL, JSON, AI agents, and automation all normalize to semantic intent before feeding into the Foundgine planner, which routes to SQL, InMemory, or future providers. The goal is to avoid implementing separate execution semantics for every interface an application exposes.

The intermediate plan is the architectural linchpin. It is the boundary between semantic intent and physical execution, and it gives the runtime a place to preserve authorization constraints, validate dependencies, rewrite operations, estimate cost, reason about provider capabilities, optimize execution, and produce execution evidence. This is the core mechanism that allows multiple input surfaces and providers to share a single execution semantics.

Equally important is the distinction between the semantic model and the persistence model. A persistence model describes how data is stored; a semantic model describes what an application is willing to expose and operate on. These models do not have to be identical. The semantic surface can be smaller, safer, and more purposeful than the physical model. For example, a persistence model might contain internal fields like TenantId or InternalRiskScore that an application-facing semantic model deliberately does not expose to callers.

Foundgine and AI Agents

AI agents change the data-access paradigm in ways that make a semantic execution boundary essential. The naive pattern — AI → generate SQL → database — grants the model authoritative control over query construction and gives it an implicit path to the underlying data. An AI model can decide what it wants to accomplish, but it should not become the authority over which application data it is allowed to access, and it should never need direct database credentials.

Foundgine deliberately inverts that model. The flow becomes:

AI Agent → structured intent → Foundgine (resolve / validate / authorize / plan / execute) → PostgreSQL

The application stays in control of authorization and execution while AI and other structured callers use application-defined capabilities. The agent requests what it needs; Foundgine determines what is permitted and how it is executed.

The ecosystem includes dedicated AI integration surfaces. Foundgine.AI provides tool integration built on Microsoft.Extensions.AI, while Foundgine.Agent.OpenAI offers OpenAI agent integration. For Model Context Protocol tooling, Foundgine.MCP is a first-class adapter that exposes semantic capabilities through the MCP Streamable HTTP transport at /mcp, with discovery metadata available at .well-known/mcp.json. Identity, tenant context, and authorization remain host-owned and are supplied through SecurityExecutionContext.

Performance on the agent path is measured separately from the query benchmark. The agent benchmark suite compares an agent calling Foundgine through MCP against an agent calling a conventional EF Core path directly, across workload sizes and concurrency levels, covering tool-call count, throughput, wall time, and estimated per-transaction token and context load.

The Supply Chain E2E story makes the architecture concrete: an agent flows through MCP into Foundgine and on to PostgreSQL, exercising customers, orders, order items, products, suppliers, warehouses, and carriers. PlaceOrder is the high-assurance vertical slice — combining authorization, ownership, validation, server-side pricing, inventory checks, atomic mutation, idempotency and replay protection, and execution evidence.

Performance Evidence

Foundgine's query performance was evaluated with a deterministic PostgreSQL graph workload using the CoffeeBeanery fixture. The workload spans a five-level entity graph — Customer → CustomerBankingRelationship → Contract → Transaction — seeded with 1,000 customers, 4,000 relationships, 12,000 contracts, and 48,000 transactions. Measurements ran at concurrency levels of 1, 8, and 32, with a 10-second measurement window, a 3-second warm-up, and a 5-second request timeout, across three independent successful runs.

At concurrency 32, the results are decisive:

This corresponds to approximately 20.0× the throughput of the baseline without caching, 20.4× with provider-plan caching, 16.7× lower p95 latency without the cache, and 17.0× lower p95 latency with it. Notably, the large query advantage is not dependent on provider-plan caching — even the uncached path outperforms the baseline by an order of magnitude. Reliability across the three runs was flawless: 0 application errors, 0 request timeouts, and 0 cancelled requests.

Scope matters. These results are workload-specific evidence for this relationship-heavy graph workload, not a universal claim that Foundgine is faster than every EF Core or GraphQL workload. Results depend on the workload, schema, provider versions, host, fixture, and implementation versions. Mutation performance, in particular, is more variable — the benchmark supports the conclusion that Foundgine can perform well at higher concurrency, but mutation throughput should not currently be presented as the primary performance claim. The appropriate claim is that Foundgine demonstrates strong query performance for this relationship-heavy graph workload, with provider-plan caching measured separately.

Ecosystem, Packages & Integrations

Foundgine is distributed as a coordinated set of NuGet packages rather than a single monolithic library, giving users a clear progression from provider-independent contracts and semantics through planning and execution to SQL, AI, MCP, GraphQL, AOT, and high-assurance authorization components. The latest snapshot targets .NET 9.0 at version 0.5.2 with 18 published packages and 7,801 total downloads across the ecosystem.

GraphQL integration is provided through the Hot Chocolate adapter, which converts GraphQL selections into Foundgine semantic requests — making GraphQL an interface without making GraphQL the execution model. For AI-agent discovery, the MCP adapter exposes Streamable HTTP transport at /mcp, with server metadata published at .well-known/mcp.json.

Documentation is published at Foundgine.io, and a machine-readable index (llms.txt / llms-full.md) is provided for AI-agent and LLM tooling onboarding. The project has been independently analyzed by UnofficialOS, an independent community directory for AI-agent and MCP tooling, with an AST Security Audit & Verification score of 90/100 — full marks for Edge Sandbox Safety, Open-Source License Compliance, Documentation & Quickstart Quality, and Repository Hygiene & Provenance.

Security Conformance & High-Assurance Mutations

Foundgine treats security requirements as part of the semantic execution contract. Required security invariants are propagated into execution plans and checked against provider capabilities before execution. This prevents a provider from silently executing a capability whose security guarantees it cannot preserve. The security progression currently spans invariant registration, plan-level invariant proof, SQL provider conformance, high-assurance mutation conformance, and cross-provider conformance.

Security remains a shared responsibility. Foundgine's authorization and execution boundaries are designed to reduce unsafe access paths, but authentication, secret management, transport security, rate limiting, database permissions, and deployment security remain application and infrastructure responsibilities.

High-assurance mutation security is engineered at the provider boundary. Mutation cancellation is propagated to the provider execution boundary and cannot commit after a cancellation check fails. The PostgreSQL high-assurance authorization context is lifecycle-safe: actor and tenant identity are immutable, versions are strictly monotonic, deleted identities retain a version tombstone, and a missing configured authorization context fails closed. Lifecycle writes use the same row-lock serialization boundary as mutation authorization reads.

Persisted PostgreSQL authorization evidence is cryptographically bound to its complete canonical security payload using an externally held HMAC-SHA256 key. The key lifecycle supports active, verification-only, and retired states with monotonic rotation provenance, atomic immutable ring snapshots, and safe retirement checks against persisted evidence. Unknown keys, algorithm mismatches, altered actor/tenant/state/version/fingerprint values, and tampered lifecycle tombstones all fail closed. Key rotation is supported through a verification key ring while cryptographic material remains outside the database and cache identity.

The verification story moves from deterministic behavior to real database execution, then to hostile inputs and performance, before the Supply Chain benchmark exercises the complete agent-facing boundary. The CI release workflow makes unit tests, PostgreSQL integration, authorization penetration, adversarial security, and performance jobs prerequisites for package publication:

The gates include unit tests (deterministic semantic, planning, authorization and runtime behavior), PostgreSQL integration tests (provider execution preserves semantics against a real database), authorization penetration tests (unauthorized operations rejected through the real execution path), adversarial semantic-input tests (malicious or malformed intent remains inside the semantic security boundary), a performance smoke gate (benchmark stack seeds, starts, executes and finishes in Docker), and the Supply Chain E2E story (stateful capabilities, authorization, mutation integrity and replay protection work together).

Getting Started & Current Status

The documentation index and published site at Foundgine.io are the best starting points. The site covers what Foundgine is, the AI-agents-and-PostgreSQL story, architecture, and performance — with source benchmark data held under benchmarks/ for reproducibility.

For developers beginning to evaluate the platform, the recommended path starts with the InMemory provider (Foundgine.InMemory). It lets you model the semantic surface, exercise intent resolution, planning, and authorization against a database-free runtime, and iterate quickly on the semantic model before introducing a SQL-backed workload. The project targets .NET 9.0, and Foundgine.Aot provides metadata attributes and runtime support for Native AOT-oriented deployments when you are ready to move toward trimmed, self-contained publishing.

The project is at version 0.5.x, so public API stability, provider coverage, and production deployment patterns should be treated according to the project's current release and compatibility policy. Detailed, dated engineering notes for each release are maintained in CHANGELOG.md. The repository layout maps directly to the architecture: src/Foundgine.MCP holds the MCP adapter, benchmarks/CoffeeBeanery.Performance/ contains the query benchmark runner and raw artifacts, benchmarks/AgentEndToEnd/ holds the agent-path benchmark, and docs-site/ builds the published documentation.

The repository also exposes machine-readable documentation at llms.txt / llms-full.md, which is the entry point for AI-agent-oriented onboarding — letting LLM tooling discover the semantic model, package ecosystem, and integration surfaces programmatically.

FAQ