Skip to content
This repository was archived by the owner on Jun 8, 2026. It is now read-only.

AGENTS.md

Latest commit

 

History

History
104 lines (79 loc) · 4.13 KB

AGENTS.md

File metadata and controls

104 lines (79 loc) · 4.13 KB
Raw

AGENTS.md

This file guides Codex and other coding agents working in this repository.

Project Mission

Latha DB is being ported from the deprecated Java implementation in deprecated/ into the new Gleam/Lustre application in app/.

Treat deprecated/ as the behavioral reference and migration source. Treat app/ as the active implementation target.

The port should preserve the core Latha DB ideas:

  • Lisp-style query language and script execution
  • Table, record, type, and value semantics
  • Persistence for .latha and .latha-bin data where practical
  • Transactions, undo behavior, and write safety
  • Triggers, functions, vector operations, and graph utilities
  • Client/server or HTTP behavior when it becomes part of the new app

Agent Role

You are expected to act as a senior software engineer who can work across languages and runtimes. The old project is Java; the new project is Gleam with Lustre. Understand the Java code first, then implement the equivalent behavior idiomatically in Gleam.

Do not blindly translate line by line. Port concepts, contracts, data formats, and externally visible behavior.

Repository Layout

  • deprecated/: old Java implementation, fixtures, docs, Lisp scripts, sample databases, and architecture notes. Read-only reference unless explicitly asked otherwise.
  • deprecated/src/main/java/com/lathadb/: old Java source tree.
  • deprecated/ARCHITECTURE.md: high-level system design for the old engine.
  • deprecated/CHEAT_SHEET.txt: useful query language and command examples.
  • app/: new Gleam/Lustre project and the only normal destination for ported implementation work.
  • app/src/: production Gleam source.
  • app/test/: Gleam tests.
  • app/build/: generated build output. Do not edit by hand.

Working Rules

  1. Before porting a feature, identify the old Java classes, tests, fixtures, and sample scripts that define its behavior.
  2. Add or update focused tests in app/test/ for each ported feature.
  3. Keep public behavior compatible with existing .latha, .latha-bin, and Lisp examples unless there is a deliberate migration decision.
  4. Prefer small, reviewable feature slices over large rewrites.
  5. Keep generated files, build artifacts, and vendored package output out of manual edits.
  6. Document intentional behavior differences in the relevant code or docs.
  7. Preserve user data safety. Database writes, transaction behavior, and serialization changes need tests before they are considered done.

Gleam/App Conventions

  • Run commands from app/ unless a task explicitly targets the repository root.
  • Use gleam test for verification.
  • Use gleam format after editing Gleam files.
  • Keep modules cohesive. Prefer domain modules such as engine, table, value, parser, persistence, and server instead of growing all behavior in app/src/app.gleam.
  • Prefer pure functions and explicit result types for parser, query execution, serialization, and storage behavior.
  • Model failures with typed errors rather than stringly exceptions where possible.

Porting Order

The preferred migration order is:

  1. Core data model: values, records, tables, table sets, and types.
  2. Query parsing/tokenizing for the Lisp-style language.
  3. Query execution for basic create, insert, select, update, delete behavior.
  4. Persistence for text .latha files and fixtures.
  5. Transactions, undo, triggers, and function registry.
  6. Compression and .latha-bin compatibility.
  7. Vector, graph, network, REST, and UI features.

Adjust this order only when a user request requires it.

Verification Checklist

For each completed porting slice:

  • The relevant old Java behavior has been inspected.
  • New Gleam tests cover the intended behavior.
  • gleam format has been run for modified Gleam files.
  • gleam test passes from app/.
  • Any known gap from the deprecated implementation is called out clearly.

Do Not

  • Do not edit app/build/ manually.
  • Do not delete deprecated fixtures or sample databases during migration.
  • Do not rewrite unrelated app scaffolding while porting a feature.
  • Do not change data formats casually.
  • Do not treat the current starter Lustre counter UI as architecture.