docs: bespoke halideiser documentation and Halide-specific ABI/FFI

Replace all template placeholders with Halide-specific content:
- README.adoc: pipeline flow, Halide concepts (Func/Var/schedule), hardware
  targets, use cases, architecture
- ROADMAP.adoc: Phase 0-6 covering parser, codegen, scheduling, auto-tuning,
  multi-target compilation, Idris2 proofs, ecosystem
- TOPOLOGY.md: module dependency graph and data flow
- Idris2 ABI: PipelineStage, SchedulePrimitive, HardwareTarget, TileSize,
  BufferDimension, PixelType, ValidPipeline proofs, halide_buffer_t layout
- Zig FFI: pipeline context with stages/schedules/buffers, compile, execute,
  autotune, full test suite
- 0-AI-MANIFEST.a2ml: Halide domain context and structure
- .machine_readable/: STATE, META, ECOSYSTEM, ANCHOR, AI all bespoke

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.machine_readable/6a2/AGENTIC.a2ml

@@ -6,7 +6,7 @@
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [agent-permissions]
 can-edit-source = true

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -6,12 +6,13 @@
   (version "0.1.0")
   (name "halideiser")
   (type "tool")
-  (purpose "Compile image/video pipelines to optimised Halide schedules")
+  (purpose "Compile image/video processing pipelines to optimised Halide schedules — 10-100x speedups without Halide expertise")
 
   (position-in-ecosystem
     (family "-iser acceleration frameworks")
     (meta-framework "iseriser")
     (relationship "sibling")
+    (domain "image and video processing acceleration via Halide")
     (top-3 ("typedqliser" "chapeliser" "verisimiser")))
 
   (related-projects
@@ -27,12 +28,31 @@
     (project "verisimiser"
       (relationship "sibling-priority-3")
       (description "VeriSimDB octad database augmentation"))
+    (project "futharkiser"
+      (relationship "sibling")
+      (description "Futhark GPU array programming — complementary GPU target"))
     (project "squeakwell"
       (relationship "sibling")
       (description "Database recovery via constraint propagation"))
     (project "proven"
       (relationship "dependency")
-      (description "Shared Idris2 verified library"))
+      (description "Shared Idris2 verified library — formal proof infrastructure"))
     (project "typell"
       (relationship "dependency")
-      (description "Type theory engine"))))
+      (description "Type theory engine"))
+    (project "panll"
+      (relationship "integration")
+      (description "Panel framework — pipeline visualisation and schedule explorer"))
+    (project "boj-server"
+      (relationship "integration")
+      (description "Cartridge runtime — remote pipeline compilation")))
+
+  (external-dependencies
+    (project "Halide"
+      (relationship "upstream")
+      (description "Image/video processing DSL by MIT/Google — algorithm/schedule separation")
+      (url "https://halide-lang.org")
+      (license "MIT"))
+    (project "LLVM"
+      (relationship "transitive-dependency")
+      (description "Halide compiles to native code via LLVM backends"))))

.machine_readable/6a2/META.a2ml

@@ -4,38 +4,54 @@
 
 (meta
   (version "0.1.0")
-  (last-updated "2026-03-20")
+  (last-updated "2026-03-21")
 
   (architecture-decisions
     (adr "001-iser-pattern"
       (status "accepted")
-      (context "Need to make powerful languages accessible without steep learning curves")
-      (decision "Use manifest-driven code generation: user describes WHAT, tool generates HOW")
-      (consequences "Users write zero target language code; all complexity in the -iser"))
+      (context "Need to make Halide's algorithm/schedule separation accessible without Halide expertise")
+      (decision "Use manifest-driven code generation: user describes pipeline stages in TOML, halideiser generates Halide code")
+      (consequences "Users write zero Halide code; all complexity in the -iser; 10-100x speedups accessible to non-experts"))
 
     (adr "002-abi-ffi-standard"
       (status "accepted")
-      (context "Need verified interop between Rust CLI, target language, and user code")
-      (decision "Idris2 ABI for formal proofs, Zig FFI for C-ABI bridge")
-      (consequences "Compile-time correctness guarantees; zero runtime overhead from proofs"))
+      (context "Need verified interop between Rust CLI, Halide C++ runtime, and user applications")
+      (decision "Idris2 ABI for formal proofs of pipeline correctness and buffer safety; Zig FFI for C-ABI bridge")
+      (consequences "Compile-time guarantees that buffer dimensions match between stages; zero runtime overhead from proofs"))
 
-    (adr "003-rsr-template"
+    (adr "003-halide-separation"
+      (status "accepted")
+      (context "Halide's core insight: algorithm and schedule should be separate")
+      (decision "Halideiser preserves this separation — pipeline stages define the algorithm, scheduling primitives define execution strategy")
+      (consequences "Same pipeline can be compiled for different targets (CPU/GPU/WASM) by changing only the schedule"))
+
+    (adr "004-auto-tuning"
+      (status "accepted")
+      (context "Optimal schedules depend on specific hardware — cache sizes, SIMD width, GPU warp size")
+      (decision "Implement auto-tuning: search over schedule space (tile sizes, vectorise widths, parallelism) via benchmarking")
+      (consequences "Near-optimal performance without manual tuning; tuning results cached per (pipeline, hardware) pair"))
+
+    (adr "005-rsr-template"
       (status "accepted")
       (context "Need consistent project structure across 29+ -iser repos")
       (decision "All repos cloned from rsr-template-repo with full CI/CD and governance")
       (consequences "17 workflows, SECURITY.md, CONTRIBUTING, bot directives from day one")))
 
   (development-practices
-    (language "Rust" (purpose "CLI and orchestration"))
-    (language "Idris2" (purpose "ABI formal proofs"))
-    (language "Zig" (purpose "FFI C-ABI bridge"))
-    (build-tool "cargo")
+    (language "Rust" (purpose "CLI orchestration — parse, validate, generate, build, run"))
+    (language "Idris2" (purpose "ABI formal proofs — pipeline correctness, buffer safety, schedule validity"))
+    (language "Zig" (purpose "FFI C-ABI bridge — compiled pipeline execution from any language"))
+    (language "C++" (purpose "Generated Halide code — Func/Var definitions and AOT compilation"))
+    (build-tool "cargo" (purpose "Rust CLI"))
+    (build-tool "zig build" (purpose "FFI shared/static library"))
     (ci "GitHub Actions (17 workflows)"))
 
   (design-rationale
     (principle "Manifest-driven"
-      (explanation "User intent captured in TOML; all generation is deterministic and reproducible"))
-    (principle "Formally verified bridges"
-      (explanation "Idris2 dependent types prove interface correctness at compile time"))
-    (principle "Zero target language exposure"
-      (explanation "Users never write Chapel/Julia/Futhark/etc. — the -iser handles everything"))))
+      (explanation "Pipeline described in halideiser.toml; all generation is deterministic and reproducible"))
+    (principle "Algorithm/Schedule separation"
+      (explanation "Halide's core insight preserved — same algorithm runs on CPU, GPU, or WASM by changing schedule"))
+    (principle "Formally verified buffers"
+      (explanation "Idris2 dependent types prove buffer dimensions match between stages and bounds are respected"))
+    (principle "Hardware-adaptive"
+      (explanation "Auto-tuning searches the schedule space for optimal performance on specific hardware"))))

.machine_readable/6a2/NEUROSYM.a2ml

@@ -6,7 +6,7 @@
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [hypatia-config]
 scan-enabled = true

.machine_readable/6a2/PLAYBOOK.a2ml

@@ -6,7 +6,7 @@
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [deployment]
 # method = "gitops"  # gitops | manual | ci-triggered

.machine_readable/6a2/STATE.a2ml

@@ -5,31 +5,35 @@
 (state
   (metadata
     (version "0.1.0")
-    (last-updated "2026-03-20")
+    (last-updated "2026-03-21")
     (author "Jonathan D.A. Jewell"))
 
   (project-context
     (name "halideiser")
-    (description "Compile image/video pipelines to optimised Halide schedules")
+    (description "Compile image/video processing pipelines to optimised Halide schedules")
     (status "scaffold")
     (priority "—")
     (ecosystem "-iser family (https://github.com/hyperpolymath/iseriser)"))
 
   (current-position
-    (phase "initial-scaffold")
-    (completion-percentage 5)
-    (milestone "Architecture defined, CLI scaffolded, RSR template complete"))
+    (phase "scaffold-documented")
+    (completion-percentage 10)
+    (milestone "Architecture defined, bespoke ABI/FFI/docs complete, codegen pending"))
 
   (route-to-mvp
-    (step 1 "Replace codegen stubs with target-language-specific generation")
-    (step 2 "Implement Idris2 ABI proofs for core invariants")
-    (step 3 "Build Zig FFI bridge")
-    (step 4 "Integration tests with real-world examples")
-    (step 5 "Documentation and examples"))
+    (step 1 "Implement halideiser.toml pipeline stage schema and parser")
+    (step 2 "Implement Halide Func/Var codegen from parsed pipeline stages")
+    (step 3 "Implement schedule generation with default heuristics")
+    (step 4 "Build Idris2 ABI proofs for buffer dimensions and stage connectivity")
+    (step 5 "Implement Zig FFI bridge for compiled pipeline execution")
+    (step 6 "Auto-tuning loop: benchmark, perturb schedule, select fastest")
+    (step 7 "Multi-target compilation (x86, ARM, CUDA, OpenCL, WASM)")
+    (step 8 "Integration tests with real image processing workloads"))
 
   (blockers-and-issues
     (none "Project is in scaffold phase — no blockers yet"))
 
   (critical-next-actions
-    (action "Implement codegen for primary use case")
-    (action "Write first working example end-to-end")))
+    (action "Define halideiser.toml schema for pipeline stages with buffer dimensions")
+    (action "Implement Halide algorithm codegen from pipeline description")
+    (action "Write first end-to-end example: blur + sharpen on a test image")))

.machine_readable/ai/AI.a2ml

@@ -1,16 +1,37 @@
-
-# AI Assistant Instructions
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# AI Assistant Instructions for halideiser
 
 ## Repository Focus
-- `rsr-template-repo` is treated as a Rhodium Standard Repository; obey the Rhodium policies and keep `.machine_readable/` authoritative.
-- All machine-readable content lives under `.machine_readable/` — state files (a2ml), bot directives, and contractiles.
-- Prefer to keep generated files out of source control, and regenerate them with the documented commands before committing.
+
+halideiser compiles image and video processing pipelines to optimised Halide
+schedules. It follows the hyperpolymath -iser pattern: manifest-driven code
+generation with Idris2 ABI proofs and Zig FFI bridge.
+
+Key domain concepts:
+- **Func**: Halide pure function (what to compute at each pixel)
+- **Var**: Dimension variable (x, y, channel, frame)
+- **Schedule**: How to execute (tile, vectorize, parallelize, compute_at, store_at, reorder)
+- **buffer_t**: Strided multi-dimensional buffer (min, extent, stride per dimension)
+- **Auto-tuning**: Search over schedule space for optimal performance
+
+## Architecture
+
+- `src/manifest/` — Parse `halideiser.toml` pipeline descriptions
+- `src/codegen/` — Generate Halide algorithm + schedule code
+- `src/interface/abi/` — Idris2 proofs: PipelineStage, SchedulePrimitive, HardwareTarget, BufferDimension, TileSize
+- `src/interface/ffi/` — Zig FFI: pipeline context, compile, execute, autotune
+- `src/main.rs` — Rust CLI: init, validate, generate, build, run, info
 
 ## Workflow
-1. Inspect `.machine_readable/STATE.a2ml` for blockers and next actions.
-2. Respect any constraints listed inside `.machine_readable/AGENTIC.a2ml` when tooling changes are requested.
-3. After finishing edits, update STATE with your outcomes and commit with a concise, imperative message.
 
-## Delivery Promises
-- Mention in summaries whether STATE, `.machine_readable/contractiles/`, or `.machine_readable/bot_directives/` changed.
-- Keep this file in sync with the repository's status; update it if the governance changes.
+1. Inspect `.machine_readable/6a2/STATE.a2ml` for blockers and next actions.
+2. Respect constraints in `.machine_readable/6a2/AGENTIC.a2ml`.
+3. After finishing edits, update STATE.a2ml with outcomes and commit.
+
+## Key Rules
+
+- All machine-readable content in `.machine_readable/` ONLY — never root.
+- Halide algorithm and schedule are always separate layers.
+- Idris2 ABI types must match Zig FFI enums exactly (tag values).
+- Buffer dimensions must be positive (enforced by dependent types in Idris2).
+- PMPL-1.0-or-later license on all original code.

.machine_readable/anchors/ANCHOR.a2ml

@@ -1,41 +1,42 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# ANCHOR.a2ml - authoritative anchor for this repository
+# ANCHOR.a2ml - authoritative anchor for halideiser
 
 [metadata]
 version = "1.0.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [anchor]
 schema = "hyperpolymath.anchor/1"
 repo = "hyperpolymath/halideiser"
 authority = "upstream-canonical"
 
 purpose = [
-  "Define canonical semantics and policy boundaries for this repository.",
-  "Declare what downstream/satellite repos can extend but not redefine.",
-  "Provide a stable golden path and invariant contract for release readiness.",
+  "Define canonical semantics for Halide pipeline compilation.",
+  "Declare ABI contract for pipeline stage types, scheduling primitives, and buffer layouts.",
+  "Provide golden-path validation for generated Halide code and compiled artifacts.",
 ]
 
 [identity]
-project = "{{PROJECT_NAME}}"
-kind = "{{PROJECT_KIND}}"                # language | library | service | tool
-one-sentence = "{{PROJECT_PURPOSE}}"
-domain = "{{PROJECT_DOMAIN}}"
+project = "halideiser"
+kind = "tool"
+one-sentence = "Compile image/video processing pipelines to optimised Halide schedules"
+domain = "image-processing, video-processing, halide, acceleration"
 
 [semantic-authority]
 policy = "canonical"
 
 owns = [
-  "Project semantics and specification",
-  "Invariant definitions and contractiles",
-  "Reference implementation behavior",
+  "Pipeline stage type definitions (PipelineStage, SchedulePrimitive, HardwareTarget)",
+  "Halide buffer_t layout proofs and dimension compatibility",
+  "Schedule generation heuristics and auto-tuning strategy",
+  "halideiser.toml manifest schema",
 ]
 
 [implementation-policy]
-allowed = ["Rust", "Idris2", "Zig", "Scheme", "Shell", "Just", "AsciiDoc", "Markdown"]
-forbidden = ["Node.js", "npm"]
+allowed = ["Rust", "Idris2", "Zig", "C++", "Scheme", "Shell", "Just", "AsciiDoc", "Markdown"]
+forbidden = ["Node.js", "npm", "TypeScript", "Python"]
 
 [golden-path]
 smoke-test-command = [
@@ -44,7 +45,9 @@ smoke-test-command = [
 ]
 
 success-criteria = [
-  "Core tests pass",
+  "Rust CLI builds and passes tests",
+  "Zig FFI library builds and passes unit + integration tests",
+  "Idris2 ABI type-checks with no holes",
   "Quality gates pass",
   "No unresolved critical security findings",
 ]
@@ -56,7 +59,7 @@ must-have-anchor = true
 must-have-golden-path = true
 
 [semantic-authority-files]
-language-spec = "SPECIFICATION.md"
-formal-proofs = "docs/proofs/PROOFS.adoc"
-type-theory = "docs/theory/THEORY.adoc"
-algorithms = "docs/theory/ALGORITHMS.adoc"
+formal-proofs = "src/interface/abi/"
+ffi-implementation = "src/interface/ffi/"
+manifest-schema = "src/manifest/"
+codegen = "src/codegen/"