From cc10f82204074a4738d2eddb2270983e752fab60 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Fri, 31 Jul 2026 09:23:28 +0100 Subject: [PATCH 1/4] docs: add ZIGZAG-TESTING.md methodology standard --- ZIGZAG-TESTING.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100755 ZIGZAG-TESTING.md diff --git a/ZIGZAG-TESTING.md b/ZIGZAG-TESTING.md new file mode 100755 index 00000000..ccb58573 --- /dev/null +++ b/ZIGZAG-TESTING.md @@ -0,0 +1,37 @@ +# Zigzag Testing: Aspect-Oriented Analysis and Synthesis + +## 1. Introduction +Zigzag Testing is an advanced testing methodology designed to perform aspect-oriented analysis and synthesis by charting a collection of meandering routes through a system's design. + +Unlike traditional linear integration testing (which verifies a single end-to-end happy path) or pure property-based testing (which verifies invariants on a single component), Zigzag testing deliberately crosses horizontal and vertical boundaries. It validates that cross-cutting concerns (e.g., authentication, telemetry, state persistence, failure recovery) interact correctly under chaotic, stateful traversal. + +## 2. Core Concepts + +### 2.1 Aspect-Oriented Analysis and Synthesis +Systems are composed of overlapping "aspects" (security, networking, DB logic, domain logic). Zigzag testing analyzes these aspects individually and synthesizes tests that verify their intersections. +- **Analysis**: Decompose the system into orthogonal aspects. +- **Synthesis**: Recombine these aspects into meandering operational routes that cross boundaries. + +### 2.2 Meandering Routes +A meandering route is a non-linear test execution path. Instead of `A -> B -> C`, a meandering route might trace `A -> trigger aspect X -> induce failure in B -> verify aspect Y -> C`. +- **State-Machine Traversal**: Tests are modeled as state machines where transitions represent API calls or events. +- **Random Walks**: Property-based testing engines execute random walks through the state machine. +- **Cross-Cutting Verification**: After each step, global invariants (like "no orphaned database connections" or "telemetry was emitted") are asserted. + +## 3. Implementation in the Estate +The preferred languages for implementing Zigzag Tests across the estate are **Idris2** and **Elixir**. + +### 3.1 Idris2 (Algebraic Modeling) +Idris2 is used to rigorously model the state machine and aspects using dependent types. +- **Algebras**: Define the system aspects as algebraic data types. +- **Proofs**: Use dependent types to prove that invalid states cannot be represented. +- **Code Generation**: Idris2 models can generate test sequences or API payloads that are guaranteed to be structurally valid. + +### 3.2 Elixir (Concurrency and Fault Tolerance) +Elixir (running on the BEAM) is used as the execution engine for the meandering routes. +- **PropEr / StreamData**: Use Elixir's property-based testing libraries to generate random walks through the state transitions. +- **OTP Processes**: Spawn concurrent actors to simulate meandering routes in parallel, stress-testing aspects like race conditions and distributed state. +- **Fault Injection**: Intentionally crash GenServers (aspect failure) during a route to verify self-healing (synthesis). + +## 4. Requirement (CRG Grading) +To achieve a Code Review Guidelines (CRG) Grade of **A** or **B**, core infrastructure and high-criticality services MUST implement Zigzag Testing for their critical paths. From 7ba3d467ecffd61fc5d6da4ef4e073b6a33738f7 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Fri, 31 Jul 2026 09:24:14 +0100 Subject: [PATCH 2/4] docs: require Zigzag Testing for CRG Grade B/A --- TEST-NEEDS.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md index cbf4293c..737dfe22 100644 --- a/TEST-NEEDS.md +++ b/TEST-NEEDS.md @@ -1,5 +1,8 @@ # TEST-NEEDS: standards +## CRG Grade: B/A (Targeting) +To achieve CRG Grades B and above, projects MUST implement **Zigzag Testing** for their critical paths, following the [ZIGZAG-TESTING.md](./ZIGZAG-TESTING.md) methodology. + ## CRG Grade: C — ACHIEVED 2026-04-04 All CRG C categories are present and passing. See breakdown below. From 9ed1acde64f4ea54d19fae0e9c0590b6947c452b Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sat, 1 Aug 2026 01:42:31 +0100 Subject: [PATCH 3/4] docs: update zigzag testing with spatial/temporal locality and dependencies --- ZIGZAG-TESTING.adoc | 49 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 ZIGZAG-TESTING.adoc diff --git a/ZIGZAG-TESTING.adoc b/ZIGZAG-TESTING.adoc new file mode 100644 index 00000000..cefbc099 --- /dev/null +++ b/ZIGZAG-TESTING.adoc @@ -0,0 +1,49 @@ += Zigzag Testing: Aspect-Oriented Analysis and Synthesis + +== 1. Introduction +Zigzag Testing is an advanced testing methodology designed to perform aspect-oriented analysis and synthesis by charting a collection of meandering routes through a system's design. + +Unlike traditional linear integration testing (which verifies a single end-to-end happy path) or pure property-based testing (which verifies invariants on a single component), Zigzag testing deliberately crosses horizontal and vertical boundaries. It validates that cross-cutting concerns (e.g., authentication, telemetry, state persistence, failure recovery) interact correctly under chaotic, stateful traversal. + +== 2. Core Concepts + +=== 2.1 Aspect-Oriented Analysis and Synthesis +Systems are composed of overlapping "aspects" (security, networking, DB logic, domain logic). Zigzag testing analyzes these aspects individually and synthesizes tests that verify their intersections. + +* **Analysis**: Decompose the system into orthogonal aspects. +* **Synthesis**: Recombine these aspects into meandering operational routes that cross boundaries. + +=== 2.2 Meandering Routes +A meandering route is a non-linear test execution path. Instead of `A -> B -> C`, a meandering route might trace `A -> trigger aspect X -> induce failure in B -> verify aspect Y -> C`. + +* **State-Machine Traversal**: Tests are modeled as state machines where transitions represent API calls or events. +* **Random Walks**: Property-based testing engines execute random walks through the state machine. +* **Cross-Cutting Verification**: After each step, global invariants (like "no orphaned database connections" or "telemetry was emitted") are asserted. + +=== 2.3 Scope, Locality, and Effects Analysis +A proper Zigzag Test must comprehensively map the inputs, outputs, and their ripple effects across the system. This requires tracking the state in the immediate locality of the place and time of the test, as well as the broader impact: + +* **Upstream and Downstream Dependencies**: Explicitly track systems or components that feed data into the aspect (upstream) and those that consume its outputs (downstream), including strict versioning of these dependencies. +* **Inputs and Outputs**: Map the full scope of things consumed (inputs) and things outputted (outputs) at each node of the meandering route. +* **Locality (Spatial & Temporal)**: Ensure the test context accounts for the immediate locality of the operation—both where it happens (spatial/network locality) and when it happens (temporal locality/timing). +* **Side-Effect Tracing**: Measure and verify any secondary effects felt by the system (e.g., side-channels, caching behavior, rate-limiting triggers) resulting from the primary inputs and outputs. + +== 3. Implementation in the Estate +The preferred languages for implementing Zigzag Tests across the estate are **Idris2** and **Elixir**. Additionally, reference aspects can be seen implemented natively in **Rust** (e.g., in the `patch-bridge` repository). + +=== 3.1 Idris2 (Algebraic Modeling) +Idris2 is used to rigorously model the state machine and aspects using dependent types. + +* **Algebras**: Define the system aspects as algebraic data types. +* **Proofs**: Use dependent types to prove that invalid states cannot be represented. +* **Code Generation**: Idris2 models can generate test sequences or API payloads that are guaranteed to be structurally valid. + +=== 3.2 Elixir (Concurrency and Fault Tolerance) +Elixir (running on the BEAM) is used as the execution engine for the meandering routes. + +* **PropEr / StreamData**: Use Elixir's property-based testing libraries to generate random walks through the state transitions. +* **OTP Processes**: Spawn concurrent actors to simulate meandering routes in parallel, stress-testing aspects like race conditions and distributed state. +* **Fault Injection**: Intentionally crash GenServers (aspect failure) during a route to verify self-healing (synthesis). + +== 4. Requirement (CRG Grading) +To achieve a Code Review Guidelines (CRG) Grade of **A** or **B**, core infrastructure and high-criticality services MUST implement Zigzag Testing for their critical paths. From f99c9b43475253e7af5acbdff7d4ea7f8964475c Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 13 Aug 2026 01:53:44 +0100 Subject: [PATCH 4/4] fix(ci): remove erroneous squisher-corpus guix.scm placeholder Part of estate-wide standards#426 remediation - cleanup. Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe --- a2ml/actions/validate/guix.scm | 18 ------------------ 1 file changed, 18 deletions(-) delete mode 100644 a2ml/actions/validate/guix.scm diff --git a/a2ml/actions/validate/guix.scm b/a2ml/actions/validate/guix.scm deleted file mode 100644 index c6dd7be8..00000000 --- a/a2ml/actions/validate/guix.scm +++ /dev/null @@ -1,18 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -;; guix.scm — GNU Guix package definition for squisher-corpus -;; Usage: guix shell -f guix.scm - -(use-modules (guix packages) - (guix build-system gnu) - (guix licenses)) - -(package - (name "squisher-corpus") - (version "0.1.0") - (source #f) - (build-system gnu-build-system) - (synopsis "squisher-corpus") - (description "squisher-corpus — part of the hyperpolymath ecosystem.") - (home-page "https://github.com/hyperpolymath/squisher-corpus") - (license ((@@ (guix licenses) license) "PMPL-1.0-or-later" - "https://github.com/hyperpolymath/palimpsest-license")))