Skip to main content

Query and Discovery

The orchestrator's read surface is the catalog declared in orchestrator-spec/queries.json. Every entry maps to one XRPC method under /xrpc/<nsid> and one Postgres table.

Spec shape​

{
  "name": "list_corpus_memberships",
  "entity": "corpus_membership",
  "lxm": "pub.layers.corpus.listMemberships",
  "predicate": "corpus_memberships_list",
  "params": [
    { "name": "corpus", "rust_kind": "Option<AtUri>", "http_query": "corpus", "parser": "optional_at_uri" },
    { "name": "cursor", "rust_kind": "Option<String>", "http_query": "cursor", "parser": "optional_string" },
    { "name": "limit",  "rust_kind": "Option<u32>",    "http_query": "limit",  "parser": "optional_u32" }
  ]
}

layers-codegen routes reads each entry and emits:

  • A handler function named after the spec entry (e.g. list_corpus_memberships).
  • A per-method query-param struct that unions the standard (did, cursor, limit) with the entry's filter columns.
  • A xrpc_routes(state) function that mounts the handler at /xrpc/<lxm> and attaches the auth middleware for the declared tier.

Read execution​

get_* handlers call queries::fetch_one(table, uri). list_* handlers call queries::list_table_filtered(table, filters, cursor, limit), where each Filter either matches the indexed did column directly or queries record->>'<key>'.

Pagination is keyset over uri (uri > cursor); the next-page cursor is the URI of the row immediately after the last record returned. The sentinel value null for "first page" works because Postgres treats NULL > anything as NULL.

Discovery​

Discovery is a plain list_* against corpora, ontologies, personas, etc. with did and content filters. There are no recommendation or trending heuristics in the appview itself; that shape lives in layers-observer reports if a deployment chooses to publish them.

Frontend client​

layers/web/lib/api/client.ts consumes the orchestrator's OpenAPI schema, generated by pnpm openapi:generate. The TanStack Query keys are organized by NSID prefix; each query maps to one XRPC method.