Merge pull request #257 from flyingrobots/graph-boaw

Graph BOAW

Author: flyingrobots

.ban-nondeterminism-allowlist

@@ -5,3 +5,10 @@ crates/warp-wasm/src/lib.rs
 # This is intentional - WSC is for native tooling, not WASM determinism
 crates/warp-core/src/wsc/mod.rs
 crates/warp-core/src/wsc/view.rs
+# BOAW exec uses std::env for feature-gated stride fallback (ECHO_PARALLEL_STRIDE)
+# This is a build-time debug toggle, not runtime non-determinism
+crates/warp-core/src/boaw/exec.rs
+# engine_impl uses std::env for ECHO_WORKERS configuration
+# This is read once at engine construction for worker count - determinism is not affected
+# because the worker count doesn't change execution results, only parallelism level
+crates/warp-core/src/engine_impl.rs

.githooks/pre-commit

@@ -5,7 +5,7 @@ set -euo pipefail
 # 0) Sweep stale build artifacts on odd hours (keeps target/ from ballooning)
 #    Manual: ./scripts/sweep-stale-artifacts.sh [days]
 HOUR=$(date +%H)
-if (( HOUR % 2 == 1 )) && [[ -x scripts/sweep-stale-artifacts.sh ]]; then
+if (( 10#$HOUR % 2 == 1 )) && [[ -x scripts/sweep-stale-artifacts.sh ]]; then
   scripts/sweep-stale-artifacts.sh 14
 fi
 
@@ -123,12 +123,33 @@ if [[ -x scripts/ensure_spdx.sh ]]; then
   scripts/ensure_spdx.sh || exit 1
 fi
 
-# 9) Markdown linting for staged .md files
-MD_FILES=$(echo "$STAGED" | grep -E '\.md$' || true)
-if [[ -n "$MD_FILES" ]] && command -v npx >/dev/null 2>&1; then
+# 9) Markdown formatting and linting for staged .md files
+# Use -z and --diff-filter=ACMRT to exclude deletions and handle whitespace safely
+mapfile -d '' MD_FILES < <(git diff --cached --name-only -z --diff-filter=ACMRT -- '*.md')
+if [[ ${#MD_FILES[@]} -gt 0 ]] && command -v npx >/dev/null 2>&1; then
   echo "pre-commit: linting markdown files"
-  # shellcheck disable=SC2086
-  if ! npx markdownlint-cli2 $MD_FILES; then
+
+  # Auto-format with prettier if ECHO_AUTO_FMT is enabled (handles tables, etc.)
+  case "${_auto_fmt}" in
+    1|true|TRUE|yes|YES|on|ON)
+      # Check formatting; suppress stdout (file list) but preserve stderr for errors
+      if npx prettier --check "${MD_FILES[@]}" >/dev/null; then
+        : # Already formatted
+      else
+        echo "pre-commit: running prettier on markdown files" >&2
+        # Write changes; suppress stdout but preserve stderr for errors
+        if ! npx prettier --write "${MD_FILES[@]}" >/dev/null; then
+          echo "pre-commit: prettier failed" >&2
+          exit 1
+        fi
+        echo "pre-commit: prettier updated markdown files. Aborting commit to preserve index integrity." >&2
+        echo "Hint: review changes, restage (e.g., 'git add -p' or 'git add -A'), then commit again." >&2
+        exit 1
+      fi
+      ;;
+  esac
+
+  if ! npx markdownlint-cli2 "${MD_FILES[@]}"; then
     echo "pre-commit: markdown lint failed. Run: npx markdownlint-cli2 --fix <files>" >&2
     exit 1
   fi

.github/workflows/ci.yml

@@ -74,7 +74,7 @@ jobs:
       - name: cargo test (workspace)
         run: cargo test --workspace
       - name: PRNG golden regression (warp-core)
-        run: cargo test -p warp-core --features golden_prng -- tests::next_int_golden_regression
+        run: cargo test -p warp-core --features golden_prng --test prng_golden_regression
 
   test-musl:
     name: Tests (musl)

.gitignore

@@ -44,3 +44,32 @@ temp
 # Playwright artifacts
 test-results
 playwright-report
+
+# LaTeX build artifacts (keep PDFs tracked)
+*.aux
+*.log
+*.toc
+*.lof
+*.lot
+*.fls
+*.fdb_latexmk
+*.synctex.gz
+*.xdv
+*.ps
+*.dvi
+*.out
+*.nav
+*.snm
+*.vrb
+*.run.xml
+*.bbl
+*.blg
+*.bcf
+*.idx
+*.ind
+*.ilg
+*.lbx
+_minted*
+
+# Experimental benchmark binaries (not ready for CI)
+crates/warp-benches/src/bin/

.markdownlint.json

@@ -1,7 +1,8 @@
 {
+  "MD007": { "indent": 4 },
   "MD013": false,
   "MD033": {
-    "allowed_elements": ["u8", "br", "p", "img"]
+    "allowed_elements": ["u8", "br", "p", "img", "a", "strong", "sub"]
   },
   "MD041": false,
   "MD046": {

AGENTS.md

@@ -1,5 +1,6 @@
 <!-- SPDX-License-Identifier: Apache-2.0 OR MIND-UCAL-1.0 -->
 <!-- © James Ross Ω FLYING•ROBOTS <https://github.com/flyingrobots> -->
+
 # Echo Agent Briefing
 
 Welcome to the **Echo** project. This file captures expectations for any LLM agent (and future-human collaborator) who touches the repo.
@@ -17,6 +18,106 @@ Welcome to the **Echo** project. This file captures expectations for any LLM age
 - Capture milestones, blockers, and decisions in relevant specs, ADRs, or PR descriptions.
 - AGENTS.md and `TASKS-DAG.md` are append-only; see `docs/append-only-invariants.md` plus `scripts/check-append-only.js` for the enforcement plan that CI will run before merges.
 
+## Agent Context System (2-Tier)
+
+Agents use a **2-tier context system** to maintain continuity across sessions:
+
+| Tier          | Store           | Purpose                                    | Update Frequency                 |
+| ------------- | --------------- | ------------------------------------------ | -------------------------------- |
+| **Immediate** | Redis stream    | Current task state, branch, blockers       | Every significant action         |
+| **Deep**      | Knowledge graph | Architecture decisions, patterns, entities | When learning something reusable |
+
+### Session Start (Bootstrap)
+
+1. **Read this file** (`AGENTS.md`) for project conventions
+
+2. **Check Redis handoff stream**: `echo:agent:handoff` (most recent entry)
+
+    ```text
+    XRANGE echo:agent:handoff - + COUNT 5
+    ```
+
+3. **Query knowledge graph** for relevant entities:
+
+    ```python
+    search_nodes("<feature_name>")  # e.g., "BOAW", "MaterializationBus"
+    search_nodes("Echo")            # General project context
+    ```
+
+### During Work (Continuous Updates)
+
+**Redis stream** — Update after every significant action:
+
+- Completing a task or subtask
+- Encountering a blocker
+- Making a key decision
+- Changing branches or PRs
+
+```bash
+XADD echo:agent:handoff * \
+  branch "graph-boaw" \
+  status "IN_PROGRESS" \
+  summary "Fixing determinism bug in view op emission" \
+  current_task "Updating emit_view_op_delta_scoped()" \
+  blockers "none" \
+  timestamp "<ISO-8601 timestamp>"
+```
+
+**Knowledge graph** — Create/update entities when you:
+
+- Discover an architectural pattern worth preserving
+- Complete a milestone (create `<Feature>_Phase<N>` entity)
+- Fix a non-obvious bug (create `<Feature>_BugFix` entity)
+- Make a decision that future agents should know about
+
+```json
+{
+    "name": "BOAW_Determinism_Fix",
+    "entityType": "BugFix",
+    "observations": [
+        "Root cause: emit_view_op_delta() used delta.len() for view op IDs",
+        "delta.len() is worker-local and varies by shard claim order",
+        "Fix: derive op ID from intent scope (NodeId) which is content-addressed"
+    ]
+}
+```
+
+### Session End (Handoff)
+
+Before ending a session, **always** write a handoff entry:
+
+```bash
+XADD echo:agent:handoff * \
+  branch "<current-branch>" \
+  status "<COMPLETE|IN_PROGRESS|BLOCKED>" \
+  summary "<1-2 sentence summary of what was done>" \
+  commits "<recent commit hashes and messages>" \
+  next_steps "<what the next agent should do>" \
+  blockers "<any blockers, or 'none'>" \
+  tech_debt "<any shortcuts taken that need cleanup>" \
+  test_commands "<commands to verify the work>" \
+  timestamp "<ISO-8601 timestamp>"
+```
+
+### Key Entities to Know
+
+The knowledge graph contains ~300+ entities built by prior agents. Key patterns:
+
+- `Echo Project` — Core project info and current focus
+- `<Feature>_Architecture` — Design decisions for major features
+- `<Feature>_Phase<N>` — Milestone completion records
+- `<Feature>_BugFix` — Non-obvious bug fixes worth remembering
+- `<Feature>_Tech_Debt_P<N>` — Tracked technical debt by priority
+
+### Why This Matters
+
+- **Quick tasks**: Redis handoff alone may suffice
+- **Complex tasks**: Query knowledge graph for architectural context
+- **Debugging**: Search for prior bug fixes in similar areas
+- **Decisions**: Check if prior agents already explored an approach
+
+The 2-tier system means handoffs are seamless—no context is lost between agents, and institutional knowledge accumulates over time.
+
 ## Workflows & Automation
 
 - The contributor playbook lives in `docs/workflows.md` (policy + blessed commands + automation).
@@ -42,9 +143,9 @@ Welcome to the **Echo** project. This file captures expectations for any LLM age
 ### PRs & Issues (Linkage Policy)
 
 - Every PR must be tied to a GitHub Issue.
-  - If no suitable issue exists, open one before you open the PR.
-  - Use explicit closing keywords in the PR body: include a line like `Closes #<issue-number>` so the issue auto‑closes on merge.
-  - Keep PRs single‑purpose: 1 PR = 1 thing. Avoid bundling unrelated changes.
+    - If no suitable issue exists, open one before you open the PR.
+    - Use explicit closing keywords in the PR body: include a line like `Closes #<issue-number>` so the issue auto‑closes on merge.
+    - Keep PRs single‑purpose: 1 PR = 1 thing. Avoid bundling unrelated changes.
 - Branch naming: prefer `echo/<short-feature-name>` or `timeline/<experiment>` and include the issue number in the PR title.
 - Project hygiene: assign the PR's linked issue to the correct Milestone and Board column (Blocked/Ready/Done) as part of the PR.
 
@@ -54,9 +155,9 @@ Welcome to the **Echo** project. This file captures expectations for any LLM age
 - Formatting: pre-commit auto-fixes with `cargo fmt` by default. Set `ECHO_AUTO_FMT=0` to run check-only instead.
 - Toolchain: pre-commit verifies your active toolchain matches `rust-toolchain.toml`.
 - SPDX header policy (source): every source file must start with exactly:
-  - `// SPDX-License-Identifier: Apache-2.0`
-  - `// © James Ross Ω FLYING•ROBOTS <https://github.com/flyingrobots>`
-  Use the repository scripts/hooks; do not add dual-license headers to code.
+    - `// SPDX-License-Identifier: Apache-2.0`
+    - `// © James Ross Ω FLYING•ROBOTS <https://github.com/flyingrobots>`
+      Use the repository scripts/hooks; do not add dual-license headers to code.
 
 ## Git Real