alkstore/AGENTS.md

# AGENTS.md

Operating instructions for opencode agents working in this repo. opencode
auto-loads this file as instructions, overriding the built-in defaults for
this project. Custom agents in `.opencode/agents/` inherit these rules
unless their own prompts say otherwise.

## Repo posture

This repo is in **Phase 1 (Implementation)** per `docs/sdd_process.md`.
Phase 0 concluded with the converged recommendation and the accepted ADRs
(`docs/architecture/decisions/`, `docs/architecture/README.md`); the
implementation plan (`docs/plans/implementation.md`) decomposes waves of
work into task files in `tasks/`. Three crates exist (ADR-001's Cargo
workspace split): `alkstore` (core — the contract artifact),
`alkstore-sqlite`, `alkstore-postgres`. Work proceeds task-by-task from
`tasks/`; check a task's `status` and `depends_on` before picking it up.

The architecture documents — `docs/architecture/` (core-contract.md, the
ADRs, the engine specs) — are the normative spec for code work. Where
code and ADR disagree, the ADR wins: fix the code, or (if the ADR is
genuinely wrong for a reason no ADR anticipated) raise the discrepancy
with the user before deviating. ADR amendments pre-implementation are
class-1 events under ADR-017 §2 — but that class terminates at first
release, so the window is now, not forever.

## Git Workflow

**Commit and push when reasonable.** When a change is complete and
verified, commit and push to `origin/main` without asking. This
overrides the built-in default of "only commit when explicitly asked."
"Verified" means the Verification Commands below pass for any crate the
change touches.

Exceptions — **do not** commit or push without asking:

- The change is exploratory / speculative (you're not sure the user
  wants it kept)
- The user is actively reviewing the diff and may ask for changes
- You'd be force-pushing, amending a pushed commit, creating an empty
  commit, or skipping hooks

Never commit secrets, keys, or credentials. If a commit fails or hooks
reject it, fix the issue and create a new commit — do not amend the
failed one.

Git identity is preconfigured (`glm-5.3-flash <glm-5.3-flash@alk.dev>`). Do
not change `git config`, skip hooks, or use `git commit -i`.

## Code conventions

Family-standard and pre-committed; the ADRs carry the load-bearing
decisions:

- Rust crate, `tokio` async runtime, `thiserror` error types, no panics
  in library code, no `unwrap()`/`expect()` outside tests.
- No comments in code unless the user explicitly asks. Doc comments
  (`///`, `//!`) are fine on public API — and required where a task pins
  semantics into doc text (core's docs are part of the contract).
  Inline `//` comments only when a non-obvious safety/correctness
  constraint would otherwise be missed, or the user asks.
- Module-per-file under `src/`, re-exported from `src/lib.rs`; public
  API surface is the lib re-exports.
- No CI wiring (manual CI per `docs/plans/implementation.md`).
- `#[non_exhaustive]` policy is ADR-017 §3's: on consumer-*read* types
  (`Error`, `StreamEvent`, `Job`, `Schedule`, `Wake`), never on opts
  structs consumers construct.
- Core (`alkstore`) has no driver dependencies, ever (ADR-001); payload
  encoding's `serde`/`serde_json` are the sole core deps (ADR-020 §4).
- Engine crates depend on core with the versioned path pin (ADR-017
  §4.1) — never the reverse.

## Task files

Every task file in `tasks/` carries categorical estimates (`scope`,
`risk`, `impact`, `level`) — per `docs/sdd_process.md` these are
structurally required, not optional metadata. On completion: update the
task's `status` to `completed`, and fill its **Notes** (decisions of
record the implementation made that the description didn't pin) and
**Summary** (what landed, verified how) sections — the next agent reads
those instead of re-deriving them.

## Verification Commands

Standard Rust gates, run from the workspace root; they are the merge
gate:

```
cargo build            # workspace compiles
cargo test             # workspace tests (task-scoped: cargo test -p <crate>)
cargo clippy --all-targets -- -D warnings
cargo fmt --check
```

No fuzzing is adopted (no fuzz corpus replay gate — the
alksocks/alktty/alktunnels fuzz posture was not carried into this
crate's plan); revisit only if a task or ADR introduces it.

## Architecture Context

- `docs/architecture/README.md` — the decision index; start here.
- `docs/architecture/core-contract.md` — the contract of record for the
  core crate's surface (the traits, types, error taxonomy, naming /
  reserved namespace, delivery-guarantee table, verification backlog).
- `docs/architecture/decisions/` — the accepted ADRs (ADR-001..021).
- `docs/architecture/open-questions.md` — the open-question register;
  resolved OQs cite their ADRs. Numbering is stable — never renumber;
  append.
- `docs/plans/implementation.md` — the wave-based implementation plan;
  `tasks/` decomposes its waves.
- `docs/research/` — the Phase 0 record (phase-0.md, POC specs and
  findings, the honker/pgboss reference reads,
  consumer-inventory.md). Reading it is background, not obligation;
  the ADRs supersede it where they disagree. New consumer needs still
  get a `docs/research/consumer-inventory.md` row *before* any scope
  decision assumes them (the row-first gate, ADR-017 §2).
- The SDD process and agent defs were copied from downstream projects
  (alkblobs) in the workspace; project-specific stale references were
  cleaned at Phase 0 setup (2026-10-03). If you find a section that
  assumes another crate's machinery, fix it rather than working around
  it — same discipline as stale TODOs.
- If a TODO or doc reference cites a design direction that a later ADR
  or decision rejected, the reference is stale — remove it and align;
  do not implement the rejected design.