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.subscribe(table, callback)
• client.subscribeWithSql(sql, callback, options)

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

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:

• client.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