AI Agent Coding Guidelines

When AI agents generate code for KalamDB, use these rules as defaults.

Prefer subscriptions for realtime state

For live UI or state sync, use WebSocket subscriptions:

• client.live(sql, callback, options) for materialized row state
• client.liveTableRows(table, callback, options) when table-name sugar is enough
• client.subscribeWithSql(sql, callback, options) only when you need raw protocol events

Use subscriptions as the primary realtime pattern instead of interval polling.

Keep live SQL in the strict supported shape: SELECT ... FROM ... WHERE .... Do not put ORDER BY or LIMIT inside live subscription SQL; sort or cap rows after they arrive.

Do not use interval polling for realtime updates

Avoid timer-based loops such as:

• setInterval(() => fetch(...), 1000)
• periodic SELECT queries to detect row changes
• fixed sleep loops to simulate streaming

These patterns add unnecessary load and increase staleness compared to server-push subscriptions.

Use topics and consumers for background workers

For worker pipelines and asynchronous processing, use topic consumers with ACK semantics:

• createConsumerClient({...}).consumer({...}).run(handler)
• runAgent({...}) / runConsumer({...})

This is preferred over polling tables on a schedule.

Reliability defaults for AI-generated code

• Keep writes idempotent.
• Track and restore progress with sequence IDs / offsets when reconnecting.
• Handle subscription error events explicitly.
• Use bounded retries and onFailed persistence in agent/consumer flows.

Recommended references

• Realtime Subscriptions
• Topic Consumers & ACK
• Agent Runtime
• SQL Subscriptions
• SQL Topics & Consumers