{"item":{"uri":"at://did:plc:bcgltzqazw5tb6k2g3ttenbj/dev.knotless.pull/3mzb6lkc6zn2b","kind":"pull","title":"Anyone reads what grain's labels mean, as a Bluesky labeler says it","state":"closed","author":{"did":"did:plc:bcgltzqazw5tb6k2g3ttenbj","handle":"chadtmiller.com","avatar":"https://cdn.bsky.app/img/avatar/plain/did:plc:bcgltzqazw5tb6k2g3ttenbj/bafkreig5bcb7dl7aphw6eg4e7kjkvpdshfexdvk7jldg53ypre6ecdhesu@jpeg"},"createdAt":"2026-11-01T16:01:05.508Z","comments":2},"body":"## What changes\n\n**`social.grain.moderation.describeLabels`**, a public query with no auth, answers the labels grain-serve gives out and what each one means, in the shape a Bluesky labeler's `app.bsky.labeler.service` record uses and `app.bsky.labeler.getServices` returns: `policies` is an `app.bsky.labeler.defs#labelerPolicies`. Its `labelValues` are `!takedown` and every identifier in `grain::labels::DEFINITIONS`, and its `labelValueDefinitions` are those definitions as `com.atproto.label.defs#labelValueDefinition`. Beside it is `did`, the DID the labels name as `src`, which is absent on a server with no DID. Any cache may keep the answer, since it is the same for everyone who asks.\n\n`social.grain.admin.listLabelDefinitions` stays admin-only and is unchanged.\n\n`lexicons/README.md` now maps `dev.hatk.describeLabels` to the new method and says how its shape differs: `labelValueDefinitions` replaces `definitions`.\n\n## Why\n\nThe apps need label definitions to show a label: its name, and whether it blurs, warns or hides. Today only admins can read them. The old server answered them publicly through `dev.hatk.describeLabels`.\n\nEvery definition is public. Each one is a label that can stand on something anyone reads with `com.atproto.label.queryLabels`, `csae` included, so a client needs all of them. None is admin-internal. Only the reports behind `csae` are kept from view and from models, and this method touches no reports.\n\n**Knotless:** knotless has no counterpart to mirror. Its labeler (`crates/knotless-serve/src/moderation.rs`) gives out only atproto's own `!takedown`, through `queryLabels` and `subscribeLabels`, and so defines no values of its own to describe. Knotless's `define_label` is for a repository's issue labels, not moderation. This pull follows Bluesky's labeler convention instead, as the brief asked, and sits beside the `queryLabels` grain already mirrors from knotless.\n\n## How it was checked\n\n- Added `anyone_reads_what_each_label_means` in `crates/grain-serve/tests/moderation.rs`. It calls the method through `tests/common`, so `harness/answers.mjs` checks the answer against the lexicon. It covers:\n - the answer with no token and no cache-control;\n - `!takedown` first, then the definitions in order;\n - the definitions equal to what `listLabelDefinitions` gives an admin;\n - a server with no DID leaving `did` out.\n- `node harness/lexicons.mjs origin/feature/rust` and `goat lex lint` pass on the new schema.\n- `rustfmt --check` passes on the changed files.\n- Building, the tests, clippy and coverage are left to CI.\n\n## Shortcomings\n\n- `labelValues` lists `!takedown` and grain's own definitions only. `applyLabel` lets an admin give out any value, atproto's global ones such as `!hide` or `porn` included. A value outside the list goes out undeclared, and clients fall back to atproto's global definitions for it.\n- The web still reads its own copy of the definitions (`web/src/lib/labels.ts`), and nothing calls the new method yet.\n\n## Review\n\nA quick look. The handler is `describe_labels` in `crates/grain-serve/src/moderation.rs`. Is `social.grain.moderation.describeLabels` the right name, or would you rather have one closer to `app.bsky.labeler.getServices`?\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)","html":"

What changes

social.grain.moderation.describeLabels, a public query with no auth, answers the labels grain-serve gives out and what each one means, in the shape a Bluesky labeler's app.bsky.labeler.service record uses and app.bsky.labeler.getServices returns: policies is an app.bsky.labeler.defs#labelerPolicies. Its labelValues are !takedown and every identifier in grain::labels::DEFINITIONS, and its labelValueDefinitions are those definitions as com.atproto.label.defs#labelValueDefinition. Beside it is did, the DID the labels name as src, which is absent on a server with no DID. Any cache may keep the answer, since it is the same for everyone who asks.

social.grain.admin.listLabelDefinitions stays admin-only and is unchanged.

lexicons/README.md now maps dev.hatk.describeLabels to the new method and says how its shape differs: labelValueDefinitions replaces definitions.

Why

The apps need label definitions to show a label: its name, and whether it blurs, warns or hides. Today only admins can read them. The old server answered them publicly through dev.hatk.describeLabels.

Every definition is public. Each one is a label that can stand on something anyone reads with com.atproto.label.queryLabels, csae included, so a client needs all of them. None is admin-internal. Only the reports behind csae are kept from view and from models, and this method touches no reports.

Knotless: knotless has no counterpart to mirror. Its labeler (crates/knotless-serve/src/moderation.rs) gives out only atproto's own !takedown, through queryLabels and subscribeLabels, and so defines no values of its own to describe. Knotless's define_label is for a repository's issue labels, not moderation. This pull follows Bluesky's labeler convention instead, as the brief asked, and sits beside the queryLabels grain already mirrors from knotless.

How it was checked

Added anyone_reads_what_each_label_means in crates/grain-serve/tests/moderation.rs. It calls the method through tests/common, so harness/answers.mjs checks the answer against the lexicon. It covers:\n
- the answer with no token and no cache-control;
- !takedown first, then the definitions in order;
- the definitions equal to what listLabelDefinitions gives an admin;
- a server with no DID leaving did out.
\n
node harness/lexicons.mjs origin/feature/rust and goat lex lint pass on the new schema.
rustfmt --check passes on the changed files.
Building, the tests, clippy and coverage are left to CI.

Shortcomings

labelValues lists !takedown and grain's own definitions only. applyLabel lets an admin give out any value, atproto's global ones such as !hide or porn included. A value outside the list goes out undeclared, and clients fall back to atproto's global definitions for it.
The web still reads its own copy of the definitions (web/src/lib/labels.ts), and nothing calls the new method yet.

Review

A quick look. The handler is describe_labels in crates/grain-serve/src/moderation.rs. Is social.grain.moderation.describeLabels the right name, or would you rather have one closer to app.bsky.labeler.getServices?

🤖 Generated with Claude Code

\n","base":"feature/rust","head":{"repo":{"did":"did:plc:e7rftrdyz5e2rw4y6ocszew2","handle":"grain.social","name":"grain"},"branch":"gaps/describe-labels"},"comments":[{"uri":"at://did:plc:kqi2glvzerg4dt66k64co2sl/dev.knotless.comment/3mzb6najycv2b","author":{"did":"did:plc:kqi2glvzerg4dt66k64co2sl","handle":"review.knotless.dev","bot":true},"createdAt":"2026-11-01T16:02:02.386Z","body":"This adds a public `social.grain.moderation.describeLabels` query. It returns `policies` (`labelValues` with `!takedown` first, then each entry of `labels::DEFINITIONS`, plus `labelValueDefinitions`) and `did` when the server has one. I found nothing that has to change.\n\n- **Output shape:** `Definition::json()` already emits `com.atproto.label.defs#labelValueDefinition` (identifier, severity, blurs, defaultSetting, locales), and the new lexicon refs `app.bsky.labeler.defs#labelerPolicies`, which is present in `lexicons/`.\n- **Caching:** the handler sets no headers of its own. It relies on the shared viewer layer, which marks a request with no asker as cacheable by anyone. The test checks this.\n- **Exposure:** the handler touches no reports and no admin data. The method is public as intended.\n- **Tests and docs:** the new test goes through `common`, so the lexicon check covers the answer. It also checks that the answer equals `listLabelDefinitions`, and that `did` is left out when the server has none. The README mapping is updated.\n- **Naming:** `describeLabels` under `social.grain.moderation` is fine. It keeps the old hatk name, which makes the migration table easy to read.\n- **Not run:** I did not read CI results, so the coverage gate and clippy are unchecked from my side.","html":"

This adds a public social.grain.moderation.describeLabels query. It returns policies (labelValues with !takedown first, then each entry of labels::DEFINITIONS, plus labelValueDefinitions) and did when the server has one. I found nothing that has to change.

Output shape: Definition::json() already emits com.atproto.label.defs#labelValueDefinition (identifier, severity, blurs, defaultSetting, locales), and the new lexicon refs app.bsky.labeler.defs#labelerPolicies, which is present in lexicons/.
Caching: the handler sets no headers of its own. It relies on the shared viewer layer, which marks a request with no asker as cacheable by anyone. The test checks this.
Exposure: the handler touches no reports and no admin data. The method is public as intended.
Tests and docs: the new test goes through common, so the lexicon check covers the answer. It also checks that the answer equals listLabelDefinitions, and that did is left out when the server has none. The README mapping is updated.
Naming: describeLabels under social.grain.moderation is fine. It keeps the old hatk name, which makes the migration table easy to read.
Not run: I did not read CI results, so the coverage gate and clippy are unchecked from my side.

\n","verdict":"approve","commit":"4de8a6805023fe44ef3cb9339ad42184d77c4838"},{"uri":"at://did:plc:bcgltzqazw5tb6k2g3ttenbj/dev.knotless.comment/3mzbeoqz4mb2b","author":{"did":"did:plc:bcgltzqazw5tb6k2g3ttenbj","handle":"chadtmiller.com","avatar":"https://cdn.bsky.app/img/avatar/plain/did:plc:bcgltzqazw5tb6k2g3ttenbj/bafkreig5bcb7dl7aphw6eg4e7kjkvpdshfexdvk7jldg53ypre6ecdhesu@jpeg"},"createdAt":"2026-11-01T17:50:15.665Z","body":"Landed on feature/rust in batch/three (…/3mzbdo7hmjf2b, 236806f), with its head 4de8a68 unchanged.","html":"

Landed on feature/rust in batch/three (…/3mzbdo7hmjf2b, 236806f), with its head 4de8a68 unchanged.

\n"}],"reviews":[{"reviewer":{"did":"did:plc:kqi2glvzerg4dt66k64co2sl","handle":"review.knotless.dev","bot":true},"verdict":"approve","uri":"at://did:plc:kqi2glvzerg4dt66k64co2sl/dev.knotless.comment/3mzb6najycv2b","commit":"4de8a6805023fe44ef3cb9339ad42184d77c4838","outdated":false,"maintainer":false}],"closes":[],"checks":[],"minutes":[{"runner":{"did":"did:plc:4bocpkn5zkwe4wuu4plrj5kt","handle":"runner.knotless.dev","bot":true},"minutes":2505,"freeing":[{"at":"2026-11-25T00:00:00Z","minutes":2},{"at":"2026-11-27T00:00:00Z","minutes":24},{"at":"2026-11-28T00:00:00Z","minutes":10},{"at":"2026-11-29T00:00:00Z","minutes":7},{"at":"2026-11-30T00:00:00Z","minutes":310},{"at":"2026-12-01T00:00:00Z","minutes":1355},{"at":"2026-12-02T00:00:00Z","minutes":509},{"at":"2026-12-06T00:00:00Z","minutes":43},{"at":"2026-12-07T00:00:00Z","minutes":185},{"at":"2026-12-08T00:00:00Z","minutes":16},{"at":"2026-12-09T00:00:00Z","minutes":38}],"updatedAt":"2026-11-10T01:31:15.298Z"},{"runner":{"did":"did:plc:ejh2v3z5ieqhqgz3ybk6r35x","handle":"ci.knotless.dev","bot":true},"minutes":28,"freeing":[{"at":"2026-11-29T00:00:00Z","minutes":2},{"at":"2026-11-30T00:00:00Z","minutes":7},{"at":"2026-12-01T00:00:00Z","minutes":1},{"at":"2026-12-06T00:00:00Z","minutes":6},{"at":"2026-12-07T00:00:00Z","minutes":8}],"updatedAt":"2026-11-08T00:05:20.251Z"}],"changes":{"repo":{"did":"did:plc:e7rftrdyz5e2rw4y6ocszew2","handle":"grain.social","name":"grain"},"commits":[],"files":[],"head":"4de8a6805023fe44ef3cb9339ad42184d77c4838"},"card":"/grain.social/grain/pull/did:plc:bcgltzqazw5tb6k2g3ttenbj/3mzb6lkc6zn2b/card.png?v=10387830e2d8fd15"}

grain.social/grain Switch repository Loading…

Anyone reads what grain's labels mean, as a Bluesky labeler says it

grain.social/grain

Switch repository

Loading…