docs: bespoke architecture, roadmap, topology, and ABI definitions for bqniser

Replace template placeholders with BQN-specific content across all
documentation and interface files:

- README.adoc: BQN primitives reference, CBQN architecture, use cases
- ROADMAP.adoc: Phase 0-6 plan (pattern detection, BQN codegen, CBQN
  integration, equivalence proofs, multi-source, ecosystem)
- TOPOLOGY.md: module map, data flow, key interfaces, invariants
- Types.idr: ArrayRank, BQNPrimitive, Train, Modifier1/2, UnderCombinator,
  BQNType value tags, Result codes with EvalError
- Layout.idr: BQN array memory layout (header+shape+data), BQNValueHeader,
  NumericArrayLayout, CBQN array descriptor
- Foreign.idr: CBQN C API declarations (eval, call1, call2, type, bound,
  readF64Arr, toF64, makeF64Arr, release, toCStr)
- main.zig: CBQN embedding bridge with stubbed CBQN calls
- build.zig: libbqniser build config with CBQN link placeholder
- integration_test.zig: ABI compliance tests for all bqniser_* exports
- 0-AI-MANIFEST.a2ml: bqniser-specific structure and invariants
- 6a2/*.a2ml: bespoke STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK

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

Author: hyperpolymath

.machine_readable/6a2/AGENTIC.a2ml

@@ -1,12 +1,12 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# AGENTIC.a2ml — AI agent constraints and capabilities
+# AGENTIC.a2ml — AI agent constraints and capabilities for bqniser
 # Defines what AI agents can and cannot do in this repository.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [agent-permissions]
 can-edit-source = true
@@ -22,6 +22,15 @@ can-create-files = true
 # - Never use banned languages (TypeScript, Python, Go, etc.)
 # - Never place state files in repository root (must be in .machine_readable/)
 # - Never use AGPL license (use PMPL-1.0-or-later)
+# - Never emit BQN rewrites without a corresponding Idris2 equivalence proof
+# - Never call CBQN C API directly from Rust — always via Zig FFI bridge
+# - Never assume a BQN rewrite is faster without benchmarking
+
+[bqniser-specific]
+# BQN primitive glyphs must be valid BQN (per mlochbaum.github.io/BQN/)
+# Pattern confidence must be high before emitting a rewrite
+# Array layout proofs must match CBQN's actual memory representation
+# CBQN version compatibility: target the bqnffi.h stable API
 
 [maintenance-integrity]
 fail-closed = true

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -6,12 +6,13 @@
   (version "0.1.0")
   (name "bqniser")
   (type "tool")
-  (purpose "Detect array patterns and rewrite as optimised BQN primitives")
+  (purpose "Detect array computation patterns in code and rewrite as optimised BQN primitives via CBQN")
 
   (position-in-ecosystem
     (family "-iser acceleration frameworks")
     (meta-framework "iseriser")
     (relationship "sibling")
+    (specialisation "Array language optimisation — BQN/APL family")
     (top-3 ("typedqliser" "chapeliser" "verisimiser")))
 
   (related-projects
@@ -32,7 +33,15 @@
       (description "Database recovery via constraint propagation"))
     (project "proven"
       (relationship "dependency")
-      (description "Shared Idris2 verified library"))
+      (description "Shared Idris2 verified library — reuse proofs"))
     (project "typell"
       (relationship "dependency")
-      (description "Type theory engine"))))
+      (description "Type theory engine"))
+    (project "CBQN"
+      (relationship "external-dependency")
+      (description "BQN runtime engine by dzaima — vectorised SIMD execution")
+      (url "https://github.com/dzaima/CBQN"))
+    (project "BQN"
+      (relationship "specification")
+      (description "BQN language specification by Marshall Lochbaum")
+      (url "https://mlochbaum.github.io/BQN/"))))

.machine_readable/6a2/META.a2ml

@@ -4,38 +4,62 @@
 
 (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 BQN array primitives accessible without learning APL syntax")
+      (decision "Use manifest-driven code generation: user describes WHAT, tool detects patterns and generates BQN")
+      (consequences "Users write zero BQN; all array optimisation complexity is in bqniser"))
 
     (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, CBQN runtime, and user code")
+      (decision "Idris2 ABI for formal proofs (BQN types, array layout, rewrite equivalence), Zig FFI for CBQN C-ABI bridge")
+      (consequences "Compile-time correctness guarantees; every rewrite has a proof; zero runtime overhead from proofs"))
 
-    (adr "003-rsr-template"
+    (adr "003-cbqn-runtime"
+      (status "accepted")
+      (context "Need a performant BQN execution engine with C FFI")
+      (decision "Target CBQN (dzaima/CBQN) as the BQN runtime via its bqnffi.h C API")
+      (consequences "In-process BQN evaluation; no serialisation overhead; vectorised SIMD execution"))
+
+    (adr "004-pattern-conservative"
+      (status "accepted")
+      (context "Incorrect rewrites would produce wrong results silently")
+      (decision "Only emit BQN rewrites when (a) pattern confidence is high AND (b) Idris2 equivalence proof exists")
+      (consequences "False negatives preferred over false positives; users trust the output"))
+
+    (adr "005-leading-axis-theory"
+      (status "accepted")
+      (context "BQN primitives generalise across array ranks via leading-axis theory")
+      (decision "BQNiser leverages rank polymorphism: a single rewrite handles scalars, lists, tables, and higher-rank arrays")
+      (consequences "Fewer pattern rules needed; rewrites are more general than dimension-specific alternatives"))
+
+    (adr "006-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, manifest parsing, pattern detection, orchestration"))
+    (language "BQN" (purpose "Target language for generated array expressions"))
+    (language "Idris2" (purpose "ABI formal proofs: types, layout, equivalence"))
+    (language "Zig" (purpose "FFI C-ABI bridge to CBQN runtime"))
+    (build-tool "cargo" (purpose "Rust CLI"))
+    (build-tool "zig build" (purpose "FFI bridge"))
     (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 "User intent captured in bqniser.toml; pattern detection is automatic; generation is deterministic"))
+    (principle "Formally verified rewrites"
+      (explanation "Idris2 dependent types prove each BQN rewrite preserves input-output equivalence"))
+    (principle "Rank-polymorphic by default"
+      (explanation "BQN's leading-axis theory means primitives generalise across dimensions automatically"))
+    (principle "Conservative rewriting"
+      (explanation "Only rewrite when confidence is high and equivalence proof exists; never silently produce wrong results"))
+    (principle "In-process execution"
+      (explanation "CBQN runs in-process via Zig FFI; no IPC, no serialisation, no subprocess overhead"))))

.machine_readable/6a2/NEUROSYM.a2ml

@@ -1,23 +1,28 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# NEUROSYM.a2ml — Neurosymbolic integration metadata
+# NEUROSYM.a2ml — Neurosymbolic integration metadata for bqniser
 # Configuration for Hypatia scanning and symbolic reasoning.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [hypatia-config]
 scan-enabled = true
 scan-depth = "standard"  # quick | standard | deep
 report-format = "logtalk"
 
 [symbolic-rules]
-# Custom symbolic rules for this project
-# - { name = "no-unsafe-ffi", pattern = "believe_me|unsafeCoerce", severity = "critical" }
+# BQNiser-specific symbolic rules for Hypatia
+# - Array rewrite equivalence: source pattern must produce identical output to BQN expression
+# - Rank compatibility: detected array rank must be compatible with target BQN primitive
+# - Under invertibility: G in F⌾G must have a computational inverse for the domain
+# - CBQN FFI safety: all value handles must be released after use
 
 [neural-config]
-# Neural pattern detection settings
+# Pattern detection could benefit from neural hints:
+# - Classify loop bodies as "array-like" vs "stateful" (only array-like are rewritable)
+# - Estimate speedup likelihood before committing to a rewrite
 # confidence-threshold = 0.85
 # model = "hypatia-v2"

.machine_readable/6a2/PLAYBOOK.a2ml

@@ -1,35 +1,43 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# PLAYBOOK.a2ml — Operational playbook
+# PLAYBOOK.a2ml — Operational playbook for bqniser
 # Runbooks, incident response, deployment procedures.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [deployment]
-# method = "gitops"  # gitops | manual | ci-triggered
-# target = "container"  # container | binary | library | wasm
+method = "binary"        # Binary CLI tool distributed via crates.io
+target = "binary"        # cargo install bqniser
+# Also: container image for CI/CD use (Chainguard base)
+
+[dependencies]
+# External runtime dependency: CBQN must be installed
+# - Fedora: dnf install cbqn (if packaged) or build from source
+# - Build: git clone https://github.com/dzaima/CBQN && make
+# - The Zig FFI bridge links against libcbqn at build time
 
 [incident-response]
-# 1. Check .machine_readable/STATE.a2ml for current status
+# 1. Check .machine_readable/6a2/STATE.a2ml for current status
 # 2. Review recent commits and CI results
-# 3. Run `just validate` to check compliance
+# 3. Run `just validate` to check RSR compliance
 # 4. Run `just security` to audit for vulnerabilities
+# 5. If BQN rewrite produces wrong output: check Idris2 equivalence proof
 
 [release-process]
-# 1. Update version in STATE.a2ml, META.a2ml, Justfile
+# 1. Update version in STATE.a2ml, META.a2ml, Cargo.toml, Zig build
 # 2. Run `just release-preflight` (validate + quality + security + maint-hard-pass)
-# 3. Optional local permission hardening: `just perms-snapshot && just perms-lock`
+# 3. Run `cargo test` and `cd src/interface/ffi && zig build test`
 # 4. Tag and push
-# 5. Restore local permissions if needed: `just perms-restore`
-# 6. Run `just container-push` if applicable
+# 5. Run `just container-push` if applicable
 
 [maintenance-operations]
 # Baseline audit:
 #   just maint-audit
 # Hard release gate:
 #   just maint-hard-pass
-# Permission audit:
-#   just perms-audit
+# BQN-specific checks:
+#   Verify CBQN version compatibility
+#   Run benchmark suite to detect regressions

.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 "bqniser")
-    (description "Detect array patterns and rewrite as optimised BQN primitives")
-    (status "scaffold")
+    (description "Detect array computation patterns in code and rewrite as optimised BQN primitives")
+    (target-language "BQN (via CBQN runtime)")
+    (status "scaffold — architecture defined, ABI types bespoke, codegen pending")
     (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-with-bespoke-abi")
+    (completion-percentage 10)
+    (milestone "Bespoke Idris2 ABI types (ArrayRank, BQNPrimitive, Train, Modifier, UnderCombinator), Zig FFI bridge stubs for CBQN C API, CLI scaffolded"))
 
   (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 "Pattern detection engine: AST analysis of Rust source for array patterns")
+    (step 2 "BQN codegen: emit BQN expressions using trains, under, modifiers")
+    (step 3 "CBQN integration: link Zig FFI bridge to libcbqn for in-process eval")
+    (step 4 "Idris2 equivalence proofs: prove each rewrite preserves semantics")
+    (step 5 "Numeric array round-trip: Rust Vec<f64> → BQN array → Rust Vec<f64>")
+    (step 6 "End-to-end example: detect loop, rewrite as BQN, benchmark speedup"))
 
   (blockers-and-issues
-    (none "Project is in scaffold phase — no blockers yet"))
+    (blocker "CBQN not yet linked as system library in Zig build")
+    (note "All FFI functions are correctly stubbed and return safe defaults"))
 
   (critical-next-actions
-    (action "Implement codegen for primary use case")
-    (action "Write first working example end-to-end")))
+    (action "Implement pattern detection for common loop/map/fold patterns")
+    (action "Link CBQN runtime in Zig FFI build (lib.linkSystemLibrary(\"cbqn\"))")
+    (action "Write first BQN codegen pass: simple fold → ´ rewrite")))