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.