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. See Refs & resource URIs for the grammar.

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. How the surviving results are merged is covered in Ranking & fusion.

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

Next: Sources.