Overview

The Ontology Layer exposes everything a project knows through one small contract: discover, search, fetch, and activity. Add a new kind of knowledge and it flows through the same four operations. No new endpoints, no new tools.

This is the design that keeps the API stable while the sources behind it grow. A source is a retriever that implements the contract; the service fans every request across all registered retrievers and merges the results. Adding a source is adding a retriever, not an endpoint.

The four operations

• Discover — GET .../knowledge/discover. Map every source available for a project, its availability, counts, and sync state, before you query.
• Search — POST .../knowledge/search. One natural-language query, fanned across sources, fused into a single ranked list (or grouped per source).
• Fetch — GET .../knowledge/fetch?ref=.... Resolve one hit's opaque ref to its full content object.
• Activity — POST .../knowledge/activity. Time-ordered events from the sources that carry a clock.

What a hit looks like

Every source returns the same normalized hit shape, so a caller never special-cases a source:

{
  "source": "code",
  "provider": null,
  "ref": "code|acme__platform__main|acme__platform__src/auth/session.py",
  "title": "session.py — validate_session",
  "snippet": "def validate_session(token: str) -> Principal: ...",
  "score": 0.82,
  "url": null,
  "timestamp": null,
  "resource_uri": "ontology://acme/code/...",
  "metadata": {}
}

The score is normalized to [0, 1] across sources; the ref is opaque and only meaningful to fetch.

Best-effort by design

Each source runs under a timeout. If one source errors or times out, it contributes no hits rather than failing the whole search. A query still returns what the healthy sources found.

Every call is authenticated (Authentication) and scoped to the project.

Next: Sources.