laconicd/AGENTS.md

Agents: read this before touching laconicd-backed state

Written for AI coding agents (Claude, Codex, Copilot, etc.) working on laconicd itself or on applications that persist data through it. Humans can read it too — the content is the same — but the tone addresses a specific failure mode that agents exhibit more consistently than humans.

The failure mode this document exists to prevent

Agents extending an existing laconicd-backed codebase pattern-match the visible API calls and treat them as canonical. If a codebase uses queryRecords with attribute filtering for everything — including where it's wrong — an agent will extend that usage rather than discover the Naming API.

When the wrong pattern eventually scales badly (latency grows with accumulated record versions), agents reach for workarounds within the chosen pattern — pagination, caches, compaction — rather than re-evaluating the primitive choice. That drift compounds: each workaround entrenches the wrong design.

This has happened repeatedly on real projects. The architectural cost is high, because laconicd is append-only: wrong versions persist on chain as permanent garbage that you can't silently delete.

Concrete rules for agents

1. Before designing any laconicd-backed state, read docs/PATTERNS.md

Not after a first implementation. Not when you hit a scaling wall. Before. The decision tree there is the only reliable way to pick the right primitive.

2. Do not pattern-match from existing client code as if it were canon

A gateway, SDK, or service that already uses laconicd is an existing code sample. It is not evidence that the patterns it uses are correct. Check:

• Does the client use setName / lookupNames / resolveNames at all? If not, the chances it's modelling mutable identity with queryRecords+attribute scan are high — that's almost always a latent latency bug.
• Does save_* in the client write only a Record, never a name? If your new feature has the same shape, you're about to extend the bug.
• Does the client have "pick the latest" / "sort desc and take first" logic after a queryRecords call? That is exactly what resolveName does at the chain level — the client is re-implementing it badly.

3. Questions an agent should ask itself before writing queryRecords

• "Am I looking up the current state of a logical entity?" If yes, you want the Naming API, not queryRecords.
• "Will this query return more records as the same entity gets modified over time?" If yes, you want the Naming API.
• "Am I about to write client-side code that picks the latest of the returned list?" If yes, you want the Naming API.

If any answer is yes and you still want queryRecords, stop and write a comment explaining why the Naming API doesn't fit. If you can't, the Naming API does fit.

4. Do not propose caches, pagination, or compaction as the first fix for slow reads

Slow queryRecords on a mutable-identity use case is a design smell, not a performance problem. The fixes agents reach for first are all wrong:

• TTL caches hide the latency rather than fix it. First read per window still pays the full cost.
• limit / offset pagination caps per-request fetch cost but doesn't reduce the version-per-entity multiplier.
• delete_records compaction destroys the audit trail that the immutable-Record design was supposed to provide.

If you're reaching for these, you are almost certainly on the wrong side of the decision tree in docs/PATTERNS.md. Go back and re-pick the primitive.

5. If you find a codebase already on the wrong side

Do not compound the mistake. Options in order of preference:

1. Migrate the specific feature you're touching to the Naming API. You can usually do this incrementally — start writing names on new writes, keep reading via attribute-scan until the name index is populated, then flip the read path.
2. Write an ADR documenting the debt and which class of regression will appear (latency grows with history; first timeout hit around ~N records).
3. Ship the feature on the Naming API even if the rest of the codebase doesn't — a single correct example in the codebase is worth more than consistency with a wrong pattern.

6. Read laconicd's schema and keeper source, not just the client

Before proposing a fix that involves "laconicd doesn't support X":

• gql/cerc-io/laconicd/schema.graphql — the actual read API.
• x/registry/keeper/ — the write and index path.
• proto/cerc/registry/v1/tx.proto — the mutation messages.

Many "laconicd limitations" agents assume are actually client limitations. queryRecords supports limit and offset; setName and lookupNames exist and work; NameRecord.history returns block-height-tagged prior bindings. Verify capabilities against source before recommending workarounds or upstream changes.

Why this is in its own file

A PATTERNS.md on its own is a reference document humans browse. An AGENTS.md is loaded into context and read top-to-bottom at the start of agent sessions. Calling out the failure mode explicitly — "agents tend to overlook the Naming API" — is load- bearing because the people most likely to hit the failure are the ones who wouldn't naturally pattern-match to a document titled "Patterns."

If you are reading this and you are about to write your first queryRecords call: stop. Read docs/PATTERNS.md. Then come back.