Olamaelcu Blog

A place of consensus making for the book lexicon

2026-08-22T00:00:00.000Z

There's a long thread about the formation of a book lexicon that I think is starting to demonstrate some of the worts of lexicon design. Different applications with different levels of use and applications are going to result in different needs. Instead, I think we're seeing the need for resolve more of what works within the model of ATProto; consolidation around what should be shared by the (app)views and less focus on exposing the plumbing of our individual applications to the rest of the world.

What I have seen repeated is something useful: exposing identifiers that can be useful for disambiguation. This would be the title, author and a set of identifiers that can be used to find more information about a book in one's local catalog like their ISBN, UPC, EAN, ASIN, ISSN, etc. The astute reader would notice that ISSNs and UPCs can be used for magazines and UPCs for general products. In some publishing cases, books can be printed with those constraints. As Nick mentions here that this work (emphasis mine):

[This] will be very hard, I would even say firmly, it should not be done. There will always be mismatches between datasets, and it will be an MxN problem. Exponentially hard when you account for other providers’ datasets.

I think that the local optimum solution here is for the user to have the power to make this mapping on their own case-by-case basis.

This helped me, as well as the other points made from Dracome, Hardcover and micro.blog, to come to the following proposal for the book lexicon XRPC for appviews and its expected responses:

Olamaelcu's Proposal for `community.lexicon.book`

I've made a light proposal for these records, but here it is more formalized:

Records

The goal is for five records to live under the community.lexicon.book. NSID, sharing identifier and contribution shapes via community.lexicon.book.defs.

Open for all of the record schemas:

community.lexicon.book.defs

// Shared object shapes used across the book namespace.
// `main`         — identifier object (URI + resource scheme).
// `contribution` — (subject strongRef, role) wrapper for the contributor lists in edition/work.
{
 "lexicon": 1,
 "id": "community.lexicon.book.defs",
 "description": "Shared object shapes used by community.lexicon.book.* records.",
 "defs": {
  "main": {
   "type": "object",
   "description": "An external identifier scoped to a specific source or scheme.",
   "required": ["uri", "resource"],
   "properties": {
    "uri": {
     "type": "string",
     "format": "uri",
     "minLength": 1,
     "maxLength": 2048,
     "description": "URL for vendor/library links, URN for scheme-based IDs (urn:isbn:..., urn:doi:...)."
    },
    "resource": {
     "type": "string",
     // Open set — new sources (vendors, libraries, schemes) can be added without schema changes.
     "description": "Source system or scheme this identifier belongs to.",
     "knownValues": [
      // ISBN family
      "isbn",
      "isbn13",
      "isbn10",
      // Other commerce / catalog schemes
      "asin",
      "doi",
      "oclc",
      "isbnPrefix",
      // Authority records (people/orgs)
      "isni",
      "viaf",
      "wikidata",
      // Vendor / library sites
      "openlibrary",
      "googleBooks",
      "goodreads",
      "amazon",
      "barnes",
      "hardcover",
      "bookhive",
      "bibliograph",
      "imdb",
      "official",
      // Catch-all for personal site / blog
      "web"
     ]
    }
   }
  },
  "contribution": {
   "type": "object",
   "description": "A contribution by a contributor to an edition or work.",
   "required": ["subject", "role"],
   "properties": {
    // → community.lexicon.book.contributor (strongRef: URI + CID)
    "subject": {
     "type": "ref",
     "ref": "com.atproto.repo.strongRef"
    },
    "role": {
     "type": "string",
     "knownValues": [
      "author",
      "coAuthor",
      "editor",
      "translator",
      "illustrator",
      "narrator",
      "foreword",
      "contributor"
     ]
    }
   }
  }
 }
}

community.lexicon.book.edition

// A single edition (publication event) of a book. The entry-point record.
// `work`           — OPTIONAL → community.lexicon.book.work (omit if not modeling the work abstraction).
//   `publisher`   — OPTIONAL → community.lexicon.book.publisher (small-press / unknown OK).
//   `contributors[]` — array of community.lexicon.book.defs#contribution (subject + role).
{
 "lexicon": 1,
 "id": "community.lexicon.book.edition",
 "defs": {
  "main": {
   "type": "record",
   "description": "A single edition of a book. Optionally grouped under a work record.",
   "key": "tid",
   "record": {
    "type": "object",
    "required": ["title", "createdAt"],
    "properties": {
     "title": { "type": "string", "minLength": 1, "maxLength": 2048, "maxGraphemes": 200 },
     "subtitle": { "type": "string", "maxLength": 1024, "maxGraphemes": 100 },
     "work": { "type": "ref", "ref": "com.atproto.repo.strongRef" },
     "publisher": { "type": "ref", "ref": "com.atproto.repo.strongRef" },
     "place": {
      "type": "string",
      "maxLength": 256,
      "maxGraphemes": 64,
      "description": "Place of publication. Free-form; not normalized."
     },
     "publishedYear": { "type": "integer", "minimum": 0, "maximum": 9999 },
     "language": { "type": "string", "format": "language" },
     "contributors": {
      "type": "array",
      "minLength": 0,
      "maxLength": 64,
      "items": { "type": "ref", "ref": "community.lexicon.book.defs#contribution" }
     },
     "identifiers": {
      "type": "array",
      "minLength": 0,
      "maxLength": 32,
      "items": { "type": "ref", "ref": "community.lexicon.book.defs#main" }
     },
     "description": {
      "type": "string",
      "maxLength": 8192,
      "maxGraphemes": 1024,
      "description": "Free-form description of this edition. Serves as bibliographic edition statement ('First edition', 'Revised second printing') and/or a blurb/summary."
     },
     "createdAt": { "type": "string", "format": "datetime" }
    }
   }
  }
 }
}

community.lexicon.book.work

// An abstract book work — the conceptual work that one or more editions are manifestations of.
// Opt-in: implementations may publish only editions and ignore this layer.
{
 "lexicon": 1,
 "id": "community.lexicon.book.work",
 "defs": {
  "main": {
   "type": "record",
   "description": "An abstract book work. Opt-in layer above editions.",
   "key": "tid",
   "record": {
    "type": "object",
    "required": ["title", "createdAt"],
    "properties": {
     "title": { "type": "string", "minLength": 1, "maxLength": 2048, "maxGraphemes": 200 },
     "subtitle": { "type": "string", "maxLength": 1024, "maxGraphemes": 100 },
     "originalLanguage": { "type": "string", "format": "language" },
     "firstPublishedYear": { "type": "integer", "minimum": 0, "maximum": 9999 },
     "subjects": {
      "type": "array",
      "minLength": 0,
      "maxLength": 32,
      "description": "Subject tags / genres.",
      "items": { "type": "string", "maxLength": 128, "maxGraphemes": 32 }
     },
     "contributors": {
      "type": "array",
      "minLength": 0,
      "maxLength": 64,
      "items": { "type": "ref", "ref": "community.lexicon.book.defs#contribution" }
     },
     "identifiers": {
      "type": "array",
      "minLength": 0,
      "maxLength": 32,
      "items": { "type": "ref", "ref": "community.lexicon.book.defs#main" }
     },
     "description": { "type": "string", "maxLength": 8192, "maxGraphemes": 1024 },
     "createdAt": { "type": "string", "format": "datetime" }
    }
   }
  }
 }
}

community.lexicon.book.contributor

// A person (real or pen name) credited in producing book editions or works.
// One record per real-world person; deduplicated by AppViews via `identifiers`.
// `linkedDid` lets the contributor claim ownership by pointing at their own ATProto account.
{
 "lexicon": 1,
 "id": "community.lexicon.book.contributor",
 "defs": {
  "main": {
   "type": "record",
   "description": "A person credited in producing book editions or works.",
   "key": "tid",
   "record": {
    "type": "object",
    "required": ["name", "createdAt"],
    "properties": {
     "name": { "type": "string", "minLength": 1, "maxLength": 256, "maxGraphemes": 64 },
     "aliases": {
      "type": "array",
      "minLength": 0,
      "maxLength": 16,
      "items": { "type": "string", "minLength": 1, "maxLength": 256, "maxGraphemes": 64 }
     },
     "linkedDid": { "type": "string", "format": "did" },
     "bio": { "type": "string", "maxLength": 8192, "maxGraphemes": 1024 },
     "bornYear": { "type": "integer", "minimum": 0, "maximum": 9999 },
     "diedYear": { "type": "integer", "minimum": 0, "maximum": 9999 },
     "identifiers": {
      "type": "array",
      "minLength": 0,
      "maxLength": 16,
      "items": { "type": "ref", "ref": "community.lexicon.book.defs#main" }
     },
     "createdAt": { "type": "string", "format": "datetime" }
    }
   }
  }
 }
}

community.lexicon.book.publisher

// A publishing entity (publisher house, imprint, or self-publishing author-as-publisher).
// One record per real-world entity; deduplicated by AppViews via `identifiers`.
// `imprintOf` lets imprints/divisions point up at their parent house (e.g. Tor → Macmillan).
{
 "lexicon": 1,
 "id": "community.lexicon.book.publisher",
 "defs": {
  "main": {
   "type": "record",
   "description": "A publishing entity.",
   "key": "tid",
   "record": {
    "type": "object",
    "required": ["name", "createdAt"],
    "properties": {
     "name": { "type": "string", "minLength": 1, "maxLength": 256, "maxGraphemes": 64 },
     // OPTIONAL → another community.lexicon.book.publisher record (parent house)
     "imprintOf": { "type": "ref", "ref": "com.atproto.repo.strongRef" },
     "foundingDate": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9999,
      "description": "Year founded (4-digit)."
     },
     "closingDate": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9999,
      "description": "Year ceased operations. Omit if still active."
     },
     "identifiers": {
      "type": "array",
      "minLength": 0,
      "maxLength": 16,
      "items": { "type": "ref", "ref": "community.lexicon.book.defs#main" }
     },
     "createdAt": { "type": "string", "format": "datetime" }
    }
   }
  }
 }
}

Contributors can be the author but also the translator, editor, illustrator; the list gets long and can add a complexity that some catalogs might not immediately have; making it optional when implementing a compatible AppView. This also introduces publishers as a first-class record type but also optional. I opted to make editions, the digestable unit of what makes this work work the only thing needed to get to the rest and have everything else opt-in.

Queries

The sole query needed for a bibliographic AppView to implement would be community.lexicon.book.searchEditions. It'll allow for searching by free form text text (with the query parameter q) or by an identifier (with the query identifier id, supporting the repetition of the parameter so you can send a list of values). It'll also take in an optional cursor parameter to allow for pagination in whichever way the AppView implements it, similar to other AppViews in the ATProto space. limit will be set to a suggested default of 20. Responses should be of the following shape and reason:

200: if the search completes okay even if there's no results. A key items holding the list (empty or not) of community.lexicon.book.edition records and a optional field cursor to page to the next set of results with another optional field total representing the total number of records in this result.
400: An AppView should return this if the search query is invalid to it. For example, if it supports Lucene syntax but it's invalid, return that here.

GET /xrpc/community.lexicon.book.searchEditions?
     q=<free form text>
     &id=urn:isbn:9780708899441
     &id=https://openlibrary.org/works/OL24151553W/Harlem_Shuffle?edition=key%3A/books/OL34709636M
     &id=https://www.penguinrandomhouse.com/books/608669/harlem-shuffle-by-colson-whitehead/

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    { /* entry of the community.lexicon.book.edition shape */}
  ],
  "cursor": "nextPageOfItems",
  "total": 6403

}

Other queries like the following would follow the same suit, only that they'd return 501 if the AppView doesn't support such a query:

community.lexicon.book.searchContributors
community.lexicon.book.searchPublishers
community.lexicon.book.searchWorks

In order to discover what other lexicons and queries that a bibliographic AppView supports, the following query MUST be implemented (along with .book.searchEditions):

GET /xrpc/community.lexicon.book.compatibility

HTTP/1.1 200 OK
Content-Type: application/json

{
  "queries": [
    {"nsid": "book.searchEditions"},
    {"nsid": "book.searchContributors"}
  ]
}

A client can call this in advance without having to hit a 501 when calling an endpoint unexpectedly. This idea was taken from the IndieWeb with Micropub's extension for querying for syndication targets to allow for a progressive interface. The following is the query schema:

{
 "lexicon": 1,
 "id": "community.lexicon.book.compatibility",
 "defs": {
  "main": {
   "type": "query",
   "description": "List the XRPC queries (and procedures) this AppView implements under community.lexicon.book.*. Clients use this instead of probing each NSID and tolerating 501 responses.",
   "output": {
    "encoding": "application/json",
    "schema": {
     "type": "object",
     "required": ["queries"],
     "properties": {
      "queries": {
       "type": "array",
       "items": { "type": "ref", "ref": "#queryRef" }
      }
     }
    }
   }
  },
  "queryRef": {
   "type": "object",
   "required": ["nsid"],
   "properties": {
    "nsid": {
     "type": "string",
     "format": "nsid",
     "description": "Truncated NSID relative to the 'community.lexicon' authority (e.g. 'book.searchWorks'). The full NSID is reconstructed by prepending 'community.lexicon.'."
    },
    "type": {
     "type": "string",
     "knownValues": ["query", "procedure"],
     "description": "Whether this endpoint is a query (GET) or procedure (POST). Omit if the AppView only exposes queries."
    }
   }
  }
 }
}

It's also very open to conversation (would it make more sense to inline this information into the book record itself instead of having it be a collection of strong references + thin references? What else do we gain? What else do we lose?)

We can start here for just handling discovery of books and then iterate to the shape of a review so we can then add more queries to compatible AppViews. This will eventually allow for the kind of interoperability we see with the microblogging space (with Bluesky and its kin) and the long form blogging (as we see with https://standard.site). There's another thread where conversation for the review shape can be held to help faciliate that but for now, we need consensus on this. From the conversation held in the thread, I think proposing the above will work to satisfy everyone's needs for interoperability.

Cutting Scope: Dropping Spadat and Scratchback

2026-08-12T00:00:00.000Z

In lieu of wanting to focus more on Livtet and Beats, I had to sunset both Spadat, the almost-complete Spades game over ATProto and Scratchback, the SDK that enabled some of the primitives it was based on. I might revisit them in the future when time and energy permits but for now they'll be retired. Spadat was written using Godot and Rust and Scratchback entirely in Rust with a SvelteKit frontend to allow game developers to tweak settings on-the-fly about games as well as aiming to provide Web-based leader boards.

You also won't see them anymore in https://waitlist.olamaelcu.net if you already subscribed to them. I apologize for the inconvenience.

To Livtet! To Beats!

What's the point of Bibliograph?

2026-08-11T00:00:00.000Z

So, you're curious about Bibliograph. It came out of a discussion with some folks about how we can model a book lexicon and is a direct product of what Livtet's move to rely on ATProto for all of its work — from shelving content to finding what books are trending across the Atmosphere.

The Recent Outage

If you're not familiar with the internals of SQLite, you can skip this section.

As I was importing the books from OpenLibrary's torrent dump, Bibliograph ended up generating a 48 gigabyte WAL file that locked up the little 2GB RAM machine it's running on¹. I had to do the following:

Cap the WAL size to 128M using journal_size_limit = 134217728
Lock it to be synchronous for a moment
Run a throttling on the reconnection to Olamaelcu's tap instance

All of this is described in this commit. These changes are needed to keep it running well on a tight machine and my goal is to keep it running on this sized machine for as long as possible so anyone can pick this up and run it on commodity hardware.

However, something else was happening. Can you tell what's wrong with this SQL query?

results = await db.query.books.findMany({
 where: or(
  like(books.title, `%__health_check__ __health_check__%`),
  like(books.author, `%__health_check__ __health_check__%`)
 ),
 limit,
 offset
});

Running this query against a 4G SQLite database sounds okay if you don't mind waiting 30 seconds on a 2GB RAM machine. This is what led me to do early termination. Basically, running a full-table scan on 3.4 GB of books slowed things down a lot because LIKE '%...%' can't use a B-tree index; especially within a Node loop. This __health_check__ bit is coming from Livtet every 5 minutes to make sure that Bibliograph is responsive — this was how it knew to send interactions to Bibliograph (like enriching book and author information, fetching shelving information, etc).

The Current Status

As of now (time of writing), Bibliograph knows of 5,111,432 books (currently 5,111,432 books). This allows Livtet's public search to return all of the books it knows without having to ask Google Books or OpenLibrary (directly) anymore. This also powers the logic around the soon-to-come jigsaw puzzle game that Livtet has based on the cover of books — the first of many attempts to build engaging experiences around books that don't involve reading (or just reading, you should still be reading)!

I'm very open to feedback, ideas and questions about these apps! Send feedback to their pages for Livtet and for Bibliograph.

This is why there's rate limiting! ↩

On Livtet, ATProto and the First Release

2026-08-03T00:00:00.000Z

Livtet, Who Art Thou?

Livtet is a project I've mulled over and over (and over - and over!); starting it from scratch when I discovered a new form of organizing content that worked with my sense of library sciences. I've decided to take a hard shift and put it into the public again. It used to live on SourceHut but I brought it to GitHub so I can take advantage of a few things:

Sponsorship: this project is not cheap to develop and I want it to survive
Availability: it's one thing to work with advocates of AT on https://tangled.org but it's another to get the platform that holds everyone who considers themselves a member of the open source community on it.
Collaboration: It's not to say that SourceHut and Tangled aren't collaborative platforms; we as a developer community were so burned by SourceForge that we let GitHub become [our one and only "VCS"]¹.

Protocol Implementation Driven-Development (PID²)

With all that said, Livtet has become my gateway project into the complexity of AT Protocol. I have plans to have it work with Nostr soon and had a small prototype generated by DeepSeek but I need to scale up infrastructure to handle both². In order to really operate in a communal fashion, I decided, after some conversation of not taking the initial approach that applications like Bookhive and Popfeed have in making custom lexicons for their tracking of information, and leaned into the spirit of https://lexicon.community in a small prototype called Bibliograph. I initially had a custom lexicon for it under the NSID net.olamaelcu.livtet but interoperability is way more important to me.

Bibliograph is the result of conversation with folks interested in tracking books on-protocol and some early research on what that'd look like for a real application, like Livtet to make use of it. For example, my profile page shows information that apps like Bookhive and Popfeed can start consuming to show today, thanks to the XRPC methods provided by Bibliograph. You can see the conversation that sparked it on AT Protocol Discourse - be sure to chime in!

One could eschew using Bibliograph and ingest the AT firehose themselves to compose a graph of information about books and the information around it today, combing over existing lexicons that emit such information so it provides a "community-powered backfill", so to speak. However, having folks move to the new lexicon for new work helps test out the kinks in the spec and schema.

First Release?

This brings me to the more interesting page for layfolks: Livtet's web experience should have an early release sometime this month. I'm slating it for late August as I'm also trying to work on the native mobile applications to go with it as well. Those are actually open source as I hope to demonstrate how to use the core library with it but it'll support communicating to the Livtet API (to be documented) as well as eventually using the Bibliograph XRPC directly, making it a "native" AT Protocol client. I'd love to see clients like Heron sneak in support for this, the same way it supports Standard Site subscriptions as this will show the plural power of AT Protocol and the things you can unlock with a simple API.

Let me know what you think by mentioning @olamaelcu.net on AT Proto, about Livtet on its UserInput page or sending e-mail to jacky@olamaelcu.net!

My words here - I understand that the act of making things easier to use and hiding complexity is Actually Good. I wish, at times, that the D in DVCS was something that the executive product team at GitHub focused on but that'd eat into their money. ↩
Would you believe that all of the apps under <olamaelcu.net> are running on a 2GB RAM droplet? ↩

sysinit

2026-05-11T00:00:00.000Z

This is going to be short and sweet.

You can read about the purpose of this entity — for now it's mainly the "output" of the projects Jacky until other things fall into place. Things like the kind of projects that are meant to be either flagship services or tools can be found at the projects page.

The Plans

I'm aiming to release the things I've been hammering on for some time slowly to everyone. The easiest way to be notified when a new service is available before it's made more generally available is by signing up for the waitlist. Once you're signed in and when spots are available, you'll be able to log into the services you opted into. You can view all of the projects for opting in — before you decide to commit.

The Purpose

There's a bunch of things I want to build and contribute to and it's not enough to just write about it. There's enough space now seeing that I'm (Jacky) largely a free agent and I'd like to spend that time working on something I've written and engaged in for the last few years — the open social Web. I'll have time for folks who'd like to talk about ideas that'd like to bring to fruition around the social Web.

The Process

The ideal flow is a bit traditional: biweekly grind on features, concept development and slinging that out to the public for commentary and review. Until a more structured approach to voting on development is in place, I'll reserve final say on what gets out there — mainly since this is all effectively pro-bono (for now).

Consider this the first download of many - to making things for people!