{"item":{"uri":"at://did:plc:bcgltzqazw5tb6k2g3ttenbj/dev.knotless.pull/3mza7mdhhjpqd","kind":"pull","title":"Lexicons are linted, and only grow from main's","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-01T06:46:45.898Z","comments":5},"body":"## What changes\n\n**A `lexicons` check.** `.knotless/workflows/lexicons.yml` runs goat v0.2.6's `lex lint` and `harness/lexicons.mjs` on pulls that change `lexicons/**`, the script or the workflow, and on pushes to main; `just lex` runs the same here. The script is knotless's, checking what goat does not: `knownValues` not `enum`, objects in new arrays, open unions, a description on every `main`, a `maxLength` on strings without a format in what people write, accounts by DID not handle, and that every schema only grows from main's (nothing removed, renamed, retyped, made required or narrowed). AGENTS.md has a \"Lexicons\" section with knotless's rules, scoped as below.\n\n**Scope.** grain's own schemas under `lexicons/social/grain`, less `unspecced/` and the ten admin methods only the old server serves (`actOnReview`, `addRepos`, `getInfo`, `getReviewQueue`, `getReviewStats`, `listRepos`, `removeRepos`, `resyncRepos`, `searchRecords`, `startScan`: none named in `crates/`), listed as `OLD` in the script, which go at cutover. The other namespaces are copies of others' schemas.\n\n**Fixed here** (the trivial ones): descriptions on the `main` of the eight records, `story.getStory` and `basePermissions`; `maxLength`s on `actor.defs#pinnedFeed` (`id`, `label`, `path`), `gallery.deleteGallery`'s `rkey` (512, a record key's most), and `registerPush`/`unregisterPush`'s `token` (4096, as grain-serve's `MOST_TOKEN_BYTES`) and `appId` (256). None of these is on main, so no published schema narrows. The old server's embedded copies are regenerated to match.\n\nMirrors knotless's `.knotless/workflows/lexicons.yml`, `harness/lexicons.mjs`, the `lex` recipe in its `Justfile`, and the \"Lexicons\" section of its `AGENTS.md`.\n\n## Why\n\nknotless's lexicons are held to the style guide and only grow from what is published; grain's were not, and feature/rust is adding many. A PDS validates records against the published schemas, so a narrowed one breaks writes out there.\n\n**Base for \"only grows\": main**, where the branch left it (`git merge-base HEAD origin/main`), as knotless does. main's schemas are the ones `publish-lexicons.yml` publishes; feature/rust's are not yet out, so changing them is free until the branch lands. Checked against `origin/feature/rust` instead, the bounds added here would read as narrowings, which they are not to anyone outside.\n\nWhere grain differs from knotless's script, and why:\n\n- **What counts as \"written\"** is followed by reachability: records, procedure input, and every def either names through refs. knotless's heuristic (a defs file is written unless the def is named `*View`) flags grain's defs files, which hold answer items (`followerItem`, `cameraItem`, ...) as often as records' parts: 100 false findings.\n- **Bounds and handles on fields already on main are not asked for**, as knotless asks for objects only in new arrays: adding them would be a narrowing the grow check refuses.\n- **A handle beside a DID** in the same object is not flagged: that is a view showing both, as Bluesky's `profileView` does.\n- **goat findings kept**: `field-name-syntax` (`id`, `type` as field names, as Bluesky's report and label views use, on published schemas), and permissioned spaces, which goat v0.2.6 cannot read (`group.json`, `privateGallery.json` are skipped from goat; `basePermissions`' `space` resource kept).\n- **`repo.applyWrites`' closed unions kept**, as `com.atproto.repo.applyWrites`' are: a write of a kind the server does not know is one it cannot apply.\n- knotless's `answers` step reads answers its screenshots recorded; grain has none, and `harness.yml` already holds grain-serve's answers to the lexicons, so it is not copied.\n\n## How it was checked\n\n`node harness/lexicons.mjs` passes here, with goat v0.2.6, against main's merge-base; against `origin/feature/rust` it names the new bounds, as it should. The workflow's first run is this pull's.\n\n## Shortcomings\n\nLeft in the script's `PENDING`, not yet published, each to fix before main:\n\n- Inputs in files other open pulls are changing (pools, private galleries): `group.pool.deleteComment`/`deleteGallery` `rkey`, `privateGallery.addMember` `space`/`actor`, `createPrivateGallery` `members[]`, `privateGallery.defs#photoInput.alt` need `maxLength`s.\n- Arrays of bare values grain-serve and the web already read and write, which need objects, with the code on both sides: `sync.indexRecords` (`uris`, `indexed`, `notFound`), `story.markViewed` `stories`, `gallery.defs#cameraItem.thumbs`, `#locationItem.thumbs` and `h3Cells`, `admin.defs#reviewItem.classifiers`, `createPrivateGallery` `members`, `getSpaceSupport` `missing`.\n\nNot done: `deploy.yml` and `publish-lexicons.yml` do not wait on `lexicons` yet. The gating pull (`infra/ci-gates`) is independent of this one; whichever lands second adds `lexicons` to their `for wf in` lists.\n\nIf the runner's checkout has no `origin/main`, the grow check is skipped and the last line says so by leaving out \"only grown since\"; the first run's log shows which.\n\n## Review\n\nThe design: the four differences from knotless's script above. Start at `harness/lexicons.mjs`.\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)","html":"

What changes

A lexicons check. .knotless/workflows/lexicons.yml runs goat v0.2.6's lex lint and harness/lexicons.mjs on pulls that change lexicons/**, the script or the workflow, and on pushes to main; just lex runs the same here. The script is knotless's, checking what goat does not: knownValues not enum, objects in new arrays, open unions, a description on every main, a maxLength on strings without a format in what people write, accounts by DID not handle, and that every schema only grows from main's (nothing removed, renamed, retyped, made required or narrowed). AGENTS.md has a \"Lexicons\" section with knotless's rules, scoped as below.

Scope. grain's own schemas under lexicons/social/grain, less unspecced/ and the ten admin methods only the old server serves (actOnReview, addRepos, getInfo, getReviewQueue, getReviewStats, listRepos, removeRepos, resyncRepos, searchRecords, startScan: none named in crates/), listed as OLD in the script, which go at cutover. The other namespaces are copies of others' schemas.

Fixed here (the trivial ones): descriptions on the main of the eight records, story.getStory and basePermissions; maxLengths on actor.defs#pinnedFeed (id, label, path), gallery.deleteGallery's rkey (512, a record key's most), and registerPush/unregisterPush's token (4096, as grain-serve's MOST_TOKEN_BYTES) and appId (256). None of these is on main, so no published schema narrows. The old server's embedded copies are regenerated to match.

Mirrors knotless's .knotless/workflows/lexicons.yml, harness/lexicons.mjs, the lex recipe in its Justfile, and the \"Lexicons\" section of its AGENTS.md.

Why

knotless's lexicons are held to the style guide and only grow from what is published; grain's were not, and feature/rust is adding many. A PDS validates records against the published schemas, so a narrowed one breaks writes out there.

Base for \"only grows\": main, where the branch left it (git merge-base HEAD origin/main), as knotless does. main's schemas are the ones publish-lexicons.yml publishes; feature/rust's are not yet out, so changing them is free until the branch lands. Checked against origin/feature/rust instead, the bounds added here would read as narrowings, which they are not to anyone outside.

Where grain differs from knotless's script, and why:

What counts as \"written\" is followed by reachability: records, procedure input, and every def either names through refs. knotless's heuristic (a defs file is written unless the def is named *View) flags grain's defs files, which hold answer items (followerItem, cameraItem, ...) as often as records' parts: 100 false findings.
Bounds and handles on fields already on main are not asked for, as knotless asks for objects only in new arrays: adding them would be a narrowing the grow check refuses.
A handle beside a DID in the same object is not flagged: that is a view showing both, as Bluesky's profileView does.
goat findings kept: field-name-syntax (id, type as field names, as Bluesky's report and label views use, on published schemas), and permissioned spaces, which goat v0.2.6 cannot read (group.json, privateGallery.json are skipped from goat; basePermissions' space resource kept).
repo.applyWrites' closed unions kept, as com.atproto.repo.applyWrites' are: a write of a kind the server does not know is one it cannot apply.
knotless's answers step reads answers its screenshots recorded; grain has none, and harness.yml already holds grain-serve's answers to the lexicons, so it is not copied.

How it was checked

node harness/lexicons.mjs passes here, with goat v0.2.6, against main's merge-base; against origin/feature/rust it names the new bounds, as it should. The workflow's first run is this pull's.

Shortcomings

Left in the script's PENDING, not yet published, each to fix before main:

Inputs in files other open pulls are changing (pools, private galleries): group.pool.deleteComment/deleteGallery rkey, privateGallery.addMember space/actor, createPrivateGallery members[], privateGallery.defs#photoInput.alt need maxLengths.
Arrays of bare values grain-serve and the web already read and write, which need objects, with the code on both sides: sync.indexRecords (uris, indexed, notFound), story.markViewed stories, gallery.defs#cameraItem.thumbs, #locationItem.thumbs and h3Cells, admin.defs#reviewItem.classifiers, createPrivateGallery members, getSpaceSupport missing.

Not done: deploy.yml and publish-lexicons.yml do not wait on lexicons yet. The gating pull (infra/ci-gates) is independent of this one; whichever lands second adds lexicons to their for wf in lists.

If the runner's checkout has no origin/main, the grow check is skipped and the last line says so by leaving out \"only grown since\"; the first run's log shows which.

Review

The design: the four differences from knotless's script above. Start at harness/lexicons.mjs.

🤖 Generated with Claude Code

\n","base":"feature/rust","head":{"repo":{"did":"did:plc:e7rftrdyz5e2rw4y6ocszew2","handle":"grain.social","name":"grain"},"branch":"infra/lexicons"},"comments":[{"uri":"at://did:plc:kqi2glvzerg4dt66k64co2sl/dev.knotless.comment/3mza7otrq5g2b","author":{"did":"did:plc:kqi2glvzerg4dt66k64co2sl","handle":"review.knotless.dev","bot":true},"createdAt":"2026-11-01T06:48:10.121Z","body":"This adds a `lexicons` workflow and `harness/lexicons.mjs`. The script runs goat's lint and some checks goat doesn't make. It also checks that every schema only grows from main's merge-base. The pull also adds `just lex` and an AGENTS.md section, and fixes the trivial findings in grain's own schemas.\n\nI read the script and the workflow. The grow check, the reachability rule for what people write, and the `PENDING` and `OLD` lists all look correct and well scoped. I checked the claim that the new bounds narrow nothing published. `registerPush`, `unregisterPush`, `pinnedFeed` and `gallery.deleteGallery` don't exist on main under those names, and `MOST_TOKEN_BYTES` is 4096 in `crates/grain-serve/src/push/mod.rs`, matching the new `token` bound. I did not read the generated lexicon JSON hunks line by line. The check runs were still queued, so I haven't seen them pass. The first `lexicons` run is the real test: its last line should read \"only grown since …\", which shows the grow check ran and `origin/main` was present on the runner.\n\nNothing here needs to change before merge.","html":"

This adds a lexicons workflow and harness/lexicons.mjs. The script runs goat's lint and some checks goat doesn't make. It also checks that every schema only grows from main's merge-base. The pull also adds just lex and an AGENTS.md section, and fixes the trivial findings in grain's own schemas.

I read the script and the workflow. The grow check, the reachability rule for what people write, and the PENDING and OLD lists all look correct and well scoped. I checked the claim that the new bounds narrow nothing published. registerPush, unregisterPush, pinnedFeed and gallery.deleteGallery don't exist on main under those names, and MOST_TOKEN_BYTES is 4096 in crates/grain-serve/src/push/mod.rs, matching the new token bound. I did not read the generated lexicon JSON hunks line by line. The check runs were still queued, so I haven't seen them pass. The first lexicons run is the real test: its last line should read \"only grown since …\", which shows the grow check ran and origin/main was present on the runner.

Nothing here needs to change before merge.

\n","verdict":"approve","commit":"586d387985d76737ed1365dffe7c8558e7936b68"},{"uri":"at://did:plc:bcgltzqazw5tb6k2g3ttenbj/dev.knotless.comment/3mzaaxgzkuij3","author":{"did":"did:plc:bcgltzqazw5tb6k2g3ttenbj","handle":"chadtmiller.com","avatar":"https://cdn.bsky.app/img/avatar/plain/did:plc:bcgltzqazw5tb6k2g3ttenbj/bafkreig5bcb7dl7aphw6eg4e7kjkvpdshfexdvk7jldg53ypre6ecdhesu@jpeg"},"createdAt":"2026-11-01T07:10:52.478Z","body":"Now stacked on the CI gates pull (at://did:plc:bcgltzqazw5tb6k2g3ttenbj/dev.knotless.pull/3mza7b7mlb7rw), merged in, so that deploy and publish-lexicons wait on lexicons too (8eed7cc). It lands after that one.","html":"

Now stacked on the CI gates pull (Deploys and lexicon publishes wait on the Rust checks too), merged in, so that deploy and publish-lexicons wait on lexicons too (8eed7cc). It lands after that one.

\n"},{"uri":"at://did:plc:kqi2glvzerg4dt66k64co2sl/dev.knotless.comment/3mzab25zsxa2b","author":{"did":"did:plc:kqi2glvzerg4dt66k64co2sl","handle":"review.knotless.dev","bot":true},"createdAt":"2026-11-01T07:12:23.712Z","body":"Since round 1 this pull merged `infra/ci-gates` and added `lexicons` to the `for wf in` lists in `deploy.yml` (both wait steps) and `publish-lexicons.yml`, plus the matching comments. That was the \"not done\" item in the description. The three lists are consistent, and the 25-minute budget is still shared across the five workflows.\n\nThe checks on this commit are all still queued, so I haven't seen any of them pass. The `lexicons` run's last line should read \"only grown since …\", which shows `origin/main` was present on the runner. Nothing needs to change before merge.","html":"

Since round 1 this pull merged infra/ci-gates and added lexicons to the for wf in lists in deploy.yml (both wait steps) and publish-lexicons.yml, plus the matching comments. That was the \"not done\" item in the description. The three lists are consistent, and the 25-minute budget is still shared across the five workflows.

The checks on this commit are all still queued, so I haven't seen any of them pass. The lexicons run's last line should read \"only grown since …\", which shows origin/main was present on the runner. Nothing needs to change before merge.

\n","verdict":"approve","commit":"3ee073dd650d0c11b8985abfaf98b5d01600fd57"},{"uri":"at://did:plc:kqi2glvzerg4dt66k64co2sl/dev.knotless.comment/3mzadpczdgw2b","author":{"did":"did:plc:kqi2glvzerg4dt66k64co2sl","handle":"review.knotless.dev","bot":true},"createdAt":"2026-11-01T08:00:01.066Z","body":"Since round 2 this pull only merged `infra/ci-gates` again, which brought in `batch/one`. That brings new Rust-side work and a few new lexicons (`getSitemap`, `muteActor`, `getArchive` and others). I read the new lexicons I sampled against the script's rules: `knownValues`, a description on every `main`, DIDs not handles, and objects in new arrays. They look fine. `getArchive`'s `actor` is a query parameter with `at-identifier`, which the rules allow.\n\nI could not read the full 7,000-line merge diff, so I only sampled those files. The checks on this commit are all still queued, so I haven't seen the `lexicons` run pass. Its output is the real test of whether the merged-in schemas satisfy the script. Its last line should read \"only grown since …\". If it names a finding in one of the new batch lexicons, fix it or add it to `PENDING`. Nothing else needs to change.","html":"

Since round 2 this pull only merged infra/ci-gates again, which brought in batch/one. That brings new Rust-side work and a few new lexicons (getSitemap, muteActor, getArchive and others). I read the new lexicons I sampled against the script's rules: knownValues, a description on every main, DIDs not handles, and objects in new arrays. They look fine. getArchive's actor is a query parameter with at-identifier, which the rules allow.

I could not read the full 7,000-line merge diff, so I only sampled those files. The checks on this commit are all still queued, so I haven't seen the lexicons run pass. Its output is the real test of whether the merged-in schemas satisfy the script. Its last line should read \"only grown since …\". If it names a finding in one of the new batch lexicons, fix it or add it to PENDING. Nothing else needs to change.

\n","verdict":"approve","commit":"a5a9c85249ebe166bd5f378575cc4e2c67f29944"},{"uri":"at://did:plc:bcgltzqazw5tb6k2g3ttenbj/dev.knotless.comment/3mzajssqppj2b","author":{"did":"did:plc:bcgltzqazw5tb6k2g3ttenbj","handle":"chadtmiller.com","avatar":"https://cdn.bsky.app/img/avatar/plain/did:plc:bcgltzqazw5tb6k2g3ttenbj/bafkreig5bcb7dl7aphw6eg4e7kjkvpdshfexdvk7jldg53ypre6ecdhesu@jpeg"},"createdAt":"2026-11-01T09:49:20.675Z","body":"Landed on feature/rust at 164794a, fast-forwarded with infra/justfile (at://did:plc:bcgltzqazw5tb6k2g3ttenbj/dev.knotless.pull/3mzaa2rxkrwa2), which contains this head and passed every check against fc5f686.","html":"

Landed on feature/rust at 164794a, fast-forwarded with infra/justfile (The Justfile runs grain-serve and the web, as knotless's does), which contains this head and passed every check against fc5f686.

\n"}],"reviews":[{"reviewer":{"did":"did:plc:kqi2glvzerg4dt66k64co2sl","handle":"review.knotless.dev","bot":true},"verdict":"approve","uri":"at://did:plc:kqi2glvzerg4dt66k64co2sl/dev.knotless.comment/3mzadpczdgw2b","commit":"a5a9c85249ebe166bd5f378575cc4e2c67f29944","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":"a5a9c85249ebe166bd5f378575cc4e2c67f29944"},"card":"/grain.social/grain/pull/did:plc:bcgltzqazw5tb6k2g3ttenbj/3mza7mdhhjpqd/card.png?v=fbb3f8fae5cd21f5"}

grain.social/grain Switch repository Loading…

Lexicons are linted, and only grow from main's

grain.social/grain

Switch repository

Loading…