Prathamesh Musale
eb9aa00816
Some checks failed
E2E Tests / test-e2e (push) Failing after 1h21m21s
Integration Tests / test-integration (push) Successful in 2h13m47s
SDK Tests / sdk_tests_authority_auctions (push) Failing after 3h11m11s
SDK Tests / sdk_tests (push) Failing after 3h11m10s
SDK Tests / sdk_tests_nameservice_expiry (push) Failing after 3h11m11s
Unit Tests / test-unit (push) Failing after 3h14m50s
Applications built on laconicd repeatedly pick the Record + attribute-
scan pattern for data that has mutable logical identity (game state,
user profiles, inventories). The query cost then grows linearly with
per-entity version count, and the fix reached for (cache, pagination,
compaction) hides the design mistake rather than correcting it. AI
agents hit this failure mode especially reliably: they pattern-match
the existing client's queryRecords usage as canon and never discover
the Naming API.
This commit adds four pieces of documentation that surface the right
primitive *before* a wrong one is committed to:
* docs/PATTERNS.md — primitive decision tree with concrete
anti-patterns (queryRecords-as-KV, compaction-for-latency,
cache-the-slow-query) and a worked example (mutable game state).
* AGENTS.md — explicit for AI coding agents; names the failure mode,
lists six rules, and tells agents to read PATTERNS.md before
writing their first queryRecords call.
* gql/cerc-io/laconicd/schema.graphql — prescriptive comments on
queryRecords (warning against mutable-identity usage),
getRecordsByIds (point-lookup clarification), and the Naming
API section (USE THIS for current-state lookups).
* README.md — new 'Designing state that lives on laconicd' section
between Usage and Tests, linking both new docs.
|
||
|---|---|---|
| .. | ||
| laconic.jpeg | ||
| PATTERNS.md | ||
