From 9c036fe46813dcbb59fdda61079f6bbf278b7be1 Mon Sep 17 00:00:00 2001 From: kzoeps Date: Wed, 7 Oct 2026 11:37:15 +0600 Subject: [PATCH] services: clarify label query support Keep unsupported API-label claims in source comments while documenting direct application queries to Labelers. --- components/StackDiagram.js | 7 ++++--- lib/navigation.js | 2 +- pages/reference/services/hypercerts-api.md | 7 ++++--- pages/reference/services/index.md | 4 ++-- pages/reference/services/labelers.md | 4 ++-- 5 files changed, 13 insertions(+), 11 deletions(-) diff --git a/components/StackDiagram.js b/components/StackDiagram.js index a3d3005..a2b1dcf 100644 --- a/components/StackDiagram.js +++ b/components/StackDiagram.js @@ -39,7 +39,7 @@ export function StackDiagram() { The Hypercerts stack - Records live in many PDSs, some hosted by the Hypercerts Foundation as Certified PDSs and some independent. The Hypercerts Relay collects changes from them, Jetstream filters those changes to Hypercerts and Certified records, and the Hypercerts API maintains a searchable view. Labelers publish labels that the API can include in query results. Applications read through the SDK or the API. To write, users sign in through the entryway, from your application or from certified.app, where they manage their account. Signed-in users and groups acting through the Certified Group Service write to the same Certified PDSs. The feed service provides feeds to applications on its own. + Records live in many PDSs, some hosted by the Hypercerts Foundation as Certified PDSs and some independent. The Hypercerts Relay collects changes from them, Jetstream filters those changes to Hypercerts and Certified records, and the Hypercerts API maintains a searchable view.{' '}{/* Labelers publish labels that the API can include in query results. */}{' '}Applications can query labelers directly for labels. Applications read through the SDK or the API. To write, users sign in through the entryway, from your application or from certified.app, where they manage their account. Signed-in users and groups acting through the Certified Group Service write to the same Certified PDSs. The feed service provides feeds to applications on its own. @@ -71,8 +71,9 @@ export function StackDiagram() { {/* Read side */} - - labels + {/* + labels */} + diff --git a/lib/navigation.js b/lib/navigation.js index 55fd7b4..ad64d5d 100644 --- a/lib/navigation.js +++ b/lib/navigation.js @@ -104,7 +104,7 @@ export const navigation = [ { title: "Entryway", path: "/reference/services/entryway" }, { title: "Certified Group Service", path: "/reference/services/certified-group-service" }, { title: "Relay and Jetstream", path: "/reference/services/relay" }, - { title: "Hypercerts API", path: "/reference/services/hypercerts-api" }, + { title: "Indexer and Hypercerts API", path: "/reference/services/hypercerts-api" }, { title: "Labelers", path: "/reference/services/labelers" }, { title: "Feed Service", path: "/reference/services/feed-service" }, ], diff --git a/pages/reference/services/hypercerts-api.md b/pages/reference/services/hypercerts-api.md index 69e46b7..72e1870 100644 --- a/pages/reference/services/hypercerts-api.md +++ b/pages/reference/services/hypercerts-api.md @@ -11,7 +11,7 @@ The **indexer** is the API's internal pipeline for building its searchable view, ## Where it fits -The indexing pipeline reads record changes delivered by [Jetstream](/reference/services/relay) and uses labels published by the [labelers](/reference/services/labelers). Applications call the Hypercerts API directly or through the [SDK](/reference/sdk). The [Feed Service](/reference/services/feed-service) is a separate reader of indexed Hypercerts data. See the [services overview](/reference/services) for the full diagram. +The indexing pipeline reads record changes delivered by [Jetstream](/reference/services/relay). Applications call the Hypercerts API directly or through the [SDK](/reference/sdk). The [Feed Service](/reference/services/feed-service) is a separate reader of indexed Hypercerts data. See the [services overview](/reference/services) for the full diagram. ## AT Protocol background @@ -35,7 +35,8 @@ The indexing pipeline: 1. **Reads records from Jetstream**, which delivers Hypercerts and Certified record changes as JSON events and keeps an archive for catching up on the past. 2. **Links related records.** An evaluation, for example, points to the activity it evaluates. The index connects those records so a query can return an activity with related context, such as its author's profile and contributors, where supported by the method. -3. **Uses labels.** It incorporates labels published by Hypercerts labelers, so results can include signals such as a quality tier or "likely test data." + + Coverage follows from the sources: the API sees records on PDSs followed by the Hypercerts Relay and in the collections Jetstream keeps. A record missing from a result may be outside that coverage. @@ -63,7 +64,7 @@ Choose another read path when it better fits your use case: - **Read a known record directly from its repository.** Use `com.atproto.repo.getRecord` when you know the record's address. See [Certified PDSs](/reference/services/certified-pdss). - **Follow live record changes.** Use Jetstream for a custom live view or lossless change processing. See [Relay and Jetstream](/reference/services/relay). -- **Read labels directly.** Query a [labeler](/reference/services/labelers) for special cases; the Hypercerts API already includes labels in its query results. +- **Read labels directly.** Query a [labeler](/reference/services/labelers) when your application needs label data. - **Design against the Lexicons.** API results follow the [Hypercerts lexicons](/lexicons/hypercerts-lexicons) and [Certified lexicons](/lexicons/certified-lexicons). ## Status and source diff --git a/pages/reference/services/index.md b/pages/reference/services/index.md index 39347f7..f4988f0 100644 --- a/pages/reference/services/index.md +++ b/pages/reference/services/index.md @@ -20,8 +20,8 @@ This section describes each service at the level a project needs to integrate wi | [Entryway](/reference/services/entryway) | Signs users in to their Certified accounts | Under development; the Certified PDSs handle sign-in today | | [Certified Group Service](/reference/services/certified-group-service) | Lets several people manage one group account with different roles | Running | | [Relay and Jetstream](/reference/services/relay) | The relay collects record changes from PDSs across the network; Jetstream filters them down to Hypercerts and Certified records | Running | -| [Hypercerts API](/reference/services/hypercerts-api) | Serves XRPC queries over a searchable view of Hypercerts and Certified records | Running | -| [Labelers](/reference/services/labelers) | Publish labels about records and accounts, such as "likely test data", that the Hypercerts API and applications can use | Running | +| [Indexer and Hypercerts API](/reference/services/hypercerts-api) | Serves XRPC queries over a searchable view of Hypercerts and Certified records | Running | +| [Labelers](/reference/services/labelers) | Publish labels about records and accounts, such as "likely test data", that applications can query directly. | Running | | [Feed Service](/reference/services/feed-service) | Serves ready-made feeds of recent Hypercerts activity | Running | ## Running services diff --git a/pages/reference/services/labelers.md b/pages/reference/services/labelers.md index 4347940..1314aca 100644 --- a/pages/reference/services/labelers.md +++ b/pages/reference/services/labelers.md @@ -9,7 +9,7 @@ Hypercerts runs two labelers. The Activity Labeler rates the quality of Hypercer ## Where it fits -The labelers sit beside the main read path. They take in records from the relay and publish labels. The [Hypercerts API](/reference/services/hypercerts-api) includes those labels in its query results, and the [Feed Service](/reference/services/feed-service) uses Orglabeler labels to filter organizations. Your application can also read labels directly. The [services overview](/reference/services) has the full diagram. +The labelers sit beside the main read path. They take in records from the relay and publish labels. Your application can read labels directly from a labeler. The [Feed Service](/reference/services/feed-service) uses Orglabeler labels to filter organizations. The [services overview](/reference/services) has the full diagram. ## AT Protocol background @@ -86,7 +86,7 @@ When you use labels: - **Treat labels as signals, not verdicts.** A `standard` organization is not a bad one. It has filled in fewer fields. - **Handle the unlabeled case.** New records and accounts are labeled a short time after they appear, so keep a fallback for subjects with no label yet. -The [Hypercerts API](/reference/services/hypercerts-api) includes labels published by the labelers. Query a labeler directly only for special cases. +For labels, query a [labeler](/reference/services/labelers) directly. ## Status and source