ASQL — Cursor rules

---
description: ASQL repo — deterministic SQL engine in Go. Read AGENTS.md for the full contract.
alwaysApply: true
---

# ASQL — Cursor rules

**Read `AGENTS.md` at the repo root first.** It holds the durable
contract: layout, determinism rules, pgwire protocol gotchas, test
tiers, commit conventions, and what-not-to-do.

This file is a short Cursor-facing summary that points at the canonical
source.

## Three things that must stay true

1. **WAL is the source of truth.** Replay the same WAL, get byte-identical
   state. No wall-clock time, no `math/rand`, no map iteration order
   dependencies in the engine, executor, or storage layers. Use
   `internal/platform/clock`.

2. **pgwire is the primary surface.** The extended query protocol must
   stay compatible with pgx v5.9+. If you add a streaming Execute path,
   send `RowDescription` eagerly — the client's `readUntilRowDescription`
   will otherwise deadlock. See `AGENTS.md` for the full OID/binary
   cheat sheet.

3. **Module path is `github.com/correodabid/asql`.** Not `asql`, not
   anything else.

## Default test loop

```
go test ./internal/...
```

Full suite before committing:

```
go test -timeout 300s ./...
```

## Commit format

```
<type>(<scope>): <imperative summary>

<why, not what>

Co-Authored-By: <Agent> <noreply@anthropic.com>
```

Types: `feat`, `fix`, `chore`, `docs`, `refactor`, `style`, `test`.
Recent scopes: `pgwire`, `deps`, `ci`, `engine`, `wal`, `storage`.

## Don't

- Don't emit emoji into source files, commit messages, or documentation.
- Don't amend pushed commits or force-push without an explicit request.
- Don't skip pre-commit hooks.
- Don't add markdown files that duplicate `AGENTS.md`.
- Don't propagate `pgx` / `pgproto3` types into the engine. Keep them at
  the transport boundary.

Full detail lives in `AGENTS.md` and the `.claude/skills/` directory.