Revise and polish project documentation

.github/workflows/docs.yml

@@ -43,7 +43,7 @@ jobs:
       - name: Assemble site
         run: |
           mkdir -p site/api
-          cp web/index.html web/main.js web/style.css web/logo.svg site/
+          cp web/index.html web/main.js web/style.css logo.svg site/
           cp zig-out/web/zodd.wasm site/
           cp -r docs/api/* site/api/
 

.gitignore

@@ -102,3 +102,4 @@ core.*
 .codex
 zig-pkg/
 web/zodd.wasm
+web/logo.svg

AGENTS.md

@@ -33,21 +33,21 @@ Priorities, in order:
 
 ## Repository Layout
 
-- `src/lib.zig`: Public API entry point. Re-exports `Relation`, `Variable`, `Iteration`, `ExecutionContext`, join helpers, and extend primitives.
+- `src/lib.zig`: Public API entry point. Re-exports `Relation`, `Variable`, `Iteration`, `Database`, join helpers, and extend primitives.
 - `src/zodd/relation.zig`: Immutable `Relation` type (sorted, deduplicated tuples).
 - `src/zodd/variable.zig`: Mutable `Variable` type for fixed-point iteration, plus the `gallop` search helper.
 - `src/zodd/iteration.zig`: `Iteration` driver for semi-naive evaluation.
 - `src/zodd/join.zig`: Merge-join algorithms (`joinHelper`, `joinInto`, `joinAnti`).
 - `src/zodd/extend.zig`: Leaper-based extension primitives (`ExtendWith`, `FilterAnti`, `ExtendAnti`, `extendInto`).
-- `src/zodd/index.zig`: Indexes for keyed lookups.
+- `src/zodd/secondary_index.zig`: Indexes for keyed lookups.
 - `src/zodd/aggregate.zig`: Group-by and aggregation operations.
 - `src/zodd/frontend/`: Datalog frontend. `program.zig` is the public `Database` API; `token.zig` and `parser.zig` parse textual Datalog;
   `ast.zig` and `builder.zig` hold the shared IR and the programmatic builder; `analyze.zig` checks safety and stratification;
   `dyntuple.zig`, `plan.zig`, `join_runtime.zig`, and `evaluator.zig` compile and run rules on the engine core.
 - `tests/`: Non-unit tests (`integration_tests.zig`, `regression_tests.zig`, `property_tests.zig`, `incremental_tests.zig`, `frontend_tests.zig`).
 - `web/`: Web frontend. `zodd_wasm.zig` is the Wasm wrapper built by `zig build wasm`; `index.html`, `main.js`, and `style.css` are the UI;
   `smoke_test.mjs` is the Node.js smoke test run by `make web-test`.
-- `examples/`: Self-contained example programs (`e1_network_reachability.zig` through `e6_dependency_resolution.zig`) built as executables via
+- `examples/`: Self-contained example programs (`e1_network_reachability.zig` through `e7_datalog_frontend.zig`) built as executables via
   `build.zig`.
 - `.github/workflows/`: CI workflows (`tests.yml` for unit and integration tests plus the Wasm smoke test, `docs.yml` for deploying the website:
   the web frontend at the site root and API docs under `/api`).
@@ -95,7 +95,7 @@ Please do not add further dependencies without prior discussion.
 - Zig version: 0.16.0 (as declared in `build.zig.zon` and the Makefile's `ZIG_LOCAL` path). CI pins the version declared in `build.zig.zon`.
 - Formatting is enforced by `zig fmt`. Run `make format` before committing.
 - Naming follows Zig standard-library conventions: `camelCase` for functions (e.g. `joinInto`, `extendInto`, `fromSlice`), `snake_case` for local
-  variables and struct fields, `PascalCase` for types and structs (e.g. `Relation`, `Variable`, `ExecutionContext`), and `SCREAMING_SNAKE_CASE` for
+  variables and struct fields, `PascalCase` for types and structs (e.g. `Relation`, `Variable`, `Database`), and `SCREAMING_SNAKE_CASE` for
   top-level compile-time constants.
 
 ## Required Validation
@@ -141,7 +141,7 @@ Good first tasks:
 
 Before coding:
 
-1. Identify which module(s) the change touches (`relation`, `variable`, `iteration`, `join`, `extend`, `index`, `aggregate`, or `context`).
+1. Identify which module(s) the change touches (`relation`, `variable`, `iteration`, `join`, `extend`, `index`, `aggregate`, or `database`).
 2. Consider whether a new join or extension needs a matching index or anti-variant.
 3. Check whether the change is public-API-visible (like re-exported from `src/lib.zig`); if so, treat it as a breaking or additive API change
    deliberately.

Makefile

@@ -68,12 +68,13 @@ lint: ## Check code style and formatting of Zig files
 	@echo "Running code style checks..."
 	$(ZIG) fmt --check $(SRC_DIR) $(TEST_DIR) web/zodd_wasm.zig
 
-web: ## Build the web frontend Wasm module and stage it under web/
+web: ## Build the web frontend Wasm module and stage it under `web/`
 	@echo "Building the web frontend Wasm module..."
 	$(ZIG) build wasm
 	cp $(BUILD_DIR)/web/zodd.wasm web/zodd.wasm
+	cp -f logo.svg web/logo.svg
 
-web-serve: web ## Build and serve the web frontend at http://localhost:8085
+web-serve: web ## Build and serve the web frontend locally
 	@echo "Serving web/ at http://localhost:8085 ..."
 	python3 -m http.server 8085 --directory web
 
@@ -93,7 +94,7 @@ docs: ## Generate API documentation
 	mkdir -p $(DOC_OUT)
 	cp -r $(BUILD_DIR)/docs/* $(DOC_OUT)
 
-docs-serve: ## Serve API documentation locally
+docs-serve: docs ## Serve API documentation locally
 	@echo "Serving documentation locally"
 	cd $(DOC_OUT) && python3 -m http.server 8000
 

ROADMAP.md

@@ -30,7 +30,7 @@ This document outlines the features implemented in Zodd and the future goals for
 - [ ] CLI
 - [ ] Streaming input
 - [x] Rule DSL (textual Datalog frontend with a parser, a builder API, stratified negation, and aggregates)
-- [ ] Query planner
+- [x] Query planner
 - [ ] Magic sets
 
 ### Development and Testing

build.zig.zon

@@ -1,6 +1,6 @@
 .{
     .name = .zodd,
-    .version = "0.1.0-alpha.4",
+    .version = "0.1.0-alpha.5",
     .fingerprint = 0x2d03181bdd24914c, // Changing this has security and trust implications.
     .minimum_zig_version = "0.16.0",
     .dependencies = .{

src/lib.zig

@@ -52,7 +52,7 @@ const variable = @import("zodd/variable.zig");
 const iteration = @import("zodd/iteration.zig");
 const join = @import("zodd/join.zig");
 const extend = @import("zodd/extend.zig");
-const index_mod = @import("zodd/index.zig");
+const index_mod = @import("zodd/secondary_index.zig");
 const aggregate_mod = @import("zodd/aggregate.zig");
 const frontend = @import("zodd/frontend/program.zig");