Foundgine gives AI agents and other callers a way to express what they want, while your application retains full control over how anything is executed. It introduces a single, application‑controlled semantic execution boundary that sits between:
-
caller intent,
-
your domain meaning,
-
your authorization rules,
-
and the actual operations performed on your data, APIs, GraphQL, MCP tools, or backend systems.
This boundary ensures that agents can propose actions, but only your application decides what is allowed, what is safe, and what is actually executed.
As applications expose more functionality to callers, you can end up with lots of individual tools/endpoints, each containing its own validation, authorization, query logic, and business rules.
Foundgine centralizes that responsibility into a semantic execution boundary. The caller expresses intent, while the application remains responsible for deciding what that intent means, what is allowed, and how it gets executed.
A complex application may have several ways to express an operation:
Application code
GraphQL
JSON
AI-generated intent
Without a common semantic execution layer, each surface tends to grow its own rules for:
- what entities and fields exist;
- which relationships can be traversed;
- which filters are valid;
- what the caller is authorized to access; and
- how the request becomes database or service operations.
That produces duplicated semantics and inconsistent security boundaries.
Retrieval can discover candidates and evidence, but retrieval is not authorization. The application owns identity and policy; providers execute the already-authorized artifact. Foundgine centralizes this responsibility.
The fastest path is the Supply Chain sample pair:
- Starter: the smallest realistic application boundary.
- Advanced: richer semantics, grounding, retrieval, authorization and adversarial testing.
- .NET —
src/csharp/samples/Foundgine.SupplyChain.Advanced: start atdocs/00-Overview-And-Setup.mdand follow 01–05. - Java —
src/java/samples/foundgine-supply-chain-advanced:SupplyChain-Advanced-Tutorial.md.
- .NET —
For the conceptual path, use docs/README.md or the documentation site.
Two callers can ask for the same thing in different words:
- Canonical: “show me overdue purchase orders from our top supplier in Texas”
- Paraphrase: “show me the overdue buys from our top seller in Texas”
Foundgine does not treat the paraphrase as a fuzzy guess at a different operation. In the Supply Chain semantic contract, Buy/Buys are declared aliases of PurchaseOrder, and Seller is a declared alias of Supplier. Both sentences are grounded onto the same canonical semantic identities before authorization or planning ever runs — the diagram below follows one request all the way from words to a database call.
Tests:
- .NET —
SupplyChainGroundingAliasTests.cs(advanced Supply Chain sample) ·SemanticAliasSynonymGroundingTests.cs(core semantics). - Java —
SupplyChainGroundingAliasParityTest.java(advanced Supply Chain sample) ·SemanticAliasSynonymGroundingParityTest.java(core semantics).
| # | Layer | What happens |
|---|---|---|
| 1 | Caller intent | The caller sends either sentence. Neither one contains SQL or provider instructions. |
| 2 | Intent representation | The request becomes structured intent — the caller never constructs a physical query directly. |
| 3 | Semantic Model | The generated contract exposes canonical meanings and their declared aliases: PurchaseOrder ← Buy, Buys and Supplier ← Vendor, Seller. |
| 4 | Semantic Operation Graph | The request becomes application meaning: overdue purchase-order semantics, a ranked “top supplier” relationship, and a Texas constraint. |
| 5 | Retrieval | Relational, fuzzy/full-text, BM25/search, or graph strategies propose candidates and evidence. They never grant authority. |
| 6 | Semantic Resolution | buys → PurchaseOrder and seller → Supplier. The aliases normalize to the same canonical identities as the original wording. |
| 7 | Authorization | Application policy runs against the resolved semantic graph and caller identity. Retrieval results cannot bypass this step. |
| 8 | Plan Binding | The authorized decision is bound to a provider-independent execution plan. |
| 9 | ExecutionIR | The executable artifact carries the resolved plan and its authorization provenance across the execution boundary. |
| 10 | Provider | Only now does a physical provider — PostgreSQL, here — receive the already-authorized artifact. |
| 11 | Execution | The provider executes the constrained plan; it does not reinterpret caller vocabulary. |
| 12 | Evidence | The result carries evidence of what was resolved and executed. Evidence records what happened — it does not grant authority. |
The invariant: alias matching changes vocabulary, not authority. “Buys” does not create a new capability, and “seller” does not create a second supplier meaning — both are application-declared paths to identities that already exist.
Aliases collapse different words onto one meaning. Sometimes the ambiguity runs the other way: the same word is a legal match for two different meanings at once, and neither the graph nor a retrieval score can tell them apart on its own.
Take the request “active customers”. Both of the following are structurally valid readings:
- a customer whose account is enabled (
Customer.AccountEnabled) - a customer who placed a recent order (
Customer.HasRecentOrder)
A fuzzy/BM25/vector retriever can legitimately return both, with close scores (0.91 vs. 0.89). Foundgine does not break the tie by picking whichever scored higher: a higher retrieval score is not evidence of what the caller meant, and authorization can’t rescue a wrong guess — a request built from the wrong meaning is still a fully authorized request. It would just be a perfectly authorized misunderstanding.
| Stage | What happens |
|---|---|
| Retrieval (fuzzy) | Every plausible reading comes back as a candidate, each with its own score and evidence. Retrieval only ever proposes — it never decides. |
| Graph-constrained resolution | Each candidate is checked against the frozen semantic contract. Both AccountEnabled and HasRecentOrder form a legal path. A legal path only proves an interpretation is possible — not that it is the one intended. |
| Grounding decision | SemanticLexicalResolver.Ground compares the two paths’ signatures — what each one means, not how it got there. The signatures differ and neither dominates on confidence, so the outcome is GroundingOutcome.RequiresClarification: Committed stays null, and both readings are listed in CompetingInterpretations, each with its own steps, confidence, and evidence. |
| Caller chooses | The competing meanings are surfaced back as a clarifying question — “Did you mean customers with an enabled account, or customers with a recent order?” — instead of silently executing a guess. |
| Same boundary as everyone else | Once the caller picks one, that single interpretation goes through the exact same Authorization → Planning → Execution path as any other request. |
The invariant: a legal semantic path is not proof of intent. When retrieval genuinely can’t tell two meanings apart, Foundgine surfaces the ambiguity instead of silently authorizing a coin flip.
The same mechanism fails closed the same way in two other cases: when a resource limit (token count, search budget, timeout) stops the search before it can prove there is only one meaning (GroundingOutcome.BudgetExceeded), and when no legal interpretation exists at all (GroundingOutcome.Unresolved). Neither one ever falls back to a best-effort guess.
Read more: Lexical grounding covers fuzzy retrieval, the resolver’s complexity bounds, and worked adversarial examples end-to-end. Grounding decisions covers the full GroundingDecision shape, the difference between “different evidence for the same meaning” and “different meanings,” and the complete active customers walkthrough, backed by a passing test.
The number of independent execution surfaces is a security and maintenance multiplier. A tool-per-capability design can give an agent dozens of places where authorization, tenant filtering and query construction are implemented differently. Foundgine centralizes the semantic decision without making a transport or database the center of the architecture.
For the deeper rationale, read:
docs/WHY-FOUNDGINE.mddocs/APPLICATION-CATEGORIES.mddocs/ARCHITECTURE.mddocs/AUTHORIZATION.mddocs/SECURITY.mddocs/AI-AGENT.md
The current source layout is consolidated into four publishable packages:
| Package | Responsibility |
|---|---|
Foundgine.Core |
Semantic model, metadata, intent, planning and provider-independent contracts |
Foundgine.Runtime |
Application-facing orchestration, authorization and execution |
Foundgine.Providers |
Storage, AI/model, MCP, AOT and other concrete integrations |
Foundgine.Extensions |
Optional framework integrations such as Hot Chocolate GraphQL |
The normal application starting point is Foundgine.Runtime + Foundgine.Providers. See the package guide for the current boundary map.
The repository contains controlled benchmarks and deterministic security tests. The public evidence distinguishes measured tool calls, latency, RPS and success/failure counts from estimated context metrics.
- Agent benchmark explorer
- Supply Chain E2E
- Security PenTest
src/csharp/benchmarks/AgentEndToEnd/README.md
Benchmark results are workload-specific and should not be generalized beyond the published experiment.
A live adversarial run of Foundgine.RedTeam against the Advanced Supply Chain sample sent 18 attack attempts — cross-tenant probes, role/identity claim spoofing, claim-scope widening, write/capability escalation, and unauthenticated-actor calls — across both the semantic authorization API and the execution/tool-calling API. Every adversarial attempt was denied or blocked; only the two intentionally-legitimate baseline calls succeeded. Full attack-by-attack results, why the two APIs' error shapes intentionally differ, and the server-side classification/correlation-id logging now implemented for the execution API: docs/SECURITY.md#red-team-pentest-results-advanced-supply-chain-sample.
dotnet restore
dotnet build
dotnet testPostgreSQL integration testing: docs/POSTGRES-E2E.md.
Foundgine's architecture is specified independently of this implementation as
the Semantic Execution (SES) standard: standards/semantic-execution/.
The standard is the authority — see SES-104
for the current implementation gap matrix and conformance/known-gaps.json
for the machine-readable status of every tracked item.
Current release: 2.2.1 · .NET 9 and Java 21
The .NET and Java implementations ship as aligned, same-numbered releases. See CHANGELOG.md for the full release notes, including what changed in 2.2.1 and every release before it.
Foundgine is licensed under the Apache License 2.0.