{"id":50922174,"url":"https://github.com/fullscreen-triangle/wind-tunnel","last_synced_at":"2026-06-16T19:30:36.544Z","repository":{"id":365026804,"uuid":"1269066423","full_name":"fullscreen-triangle/wind-tunnel","owner":"fullscreen-triangle","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-15T14:35:07.000Z","size":2488,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T15:27:04.840Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TeX","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fullscreen-triangle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-14T09:13:47.000Z","updated_at":"2026-06-15T14:36:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fullscreen-triangle/wind-tunnel","commit_stats":null,"previous_names":["fullscreen-triangle/wind-tunnel"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/fullscreen-triangle/wind-tunnel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullscreen-triangle%2Fwind-tunnel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullscreen-triangle%2Fwind-tunnel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullscreen-triangle%2Fwind-tunnel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullscreen-triangle%2Fwind-tunnel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fullscreen-triangle","download_url":"https://codeload.github.com/fullscreen-triangle/wind-tunnel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullscreen-triangle%2Fwind-tunnel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34421324,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-16T19:30:35.464Z","updated_at":"2026-06-16T19:30:36.525Z","avatar_url":"https://github.com/fullscreen-triangle.png","language":"TeX","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003ch1 align=\"center\"\u003eWindtunnel\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\u003cem\u003eCode Testing Framework\u003c/em\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/img/wind-tunnel.jpg\" alt=\"Logo\" width=\"300\"/\u003e\n\u003c/p\u003e\n\n---\n\n## The problem\n\nUnit tests, integration tests, and property-based tests are all *local queries*. Each one addresses a bounded subsystem and asks whether that subsystem behaves correctly in isolation. This is structurally insufficient.\n\nA system can satisfy every local test while failing globally. The failure mode is not unusual: individually correct data-transformation steps compose into a cycle that accumulates a semantic error invisible to any single observer. No component misbehaved. The failure resided in the cycle, not in any node.\n\nThis is not an engineering caveat — it is a theorem. A bounded observer with state capacity |K_R| cannot encode a complete correctness criterion for a system whose state complexity exceeds log₂|K_R| bits. Test suites are bounded observers. The No Template Theorem makes this precise.\n\n---\n\n## The approach\n\nAn aeronautical wind tunnel does not test individual rivets. It tests the assembled aircraft under operational load, measuring quantities — lift, drag, turbulence — that are properties of the whole. There is no expected output written on a card. The criterion is self-consistency under load.\n\nThis tool applies the same principle to software. Instead of a binary pass/fail oracle, it produces a *regime map*: a multi-dimensional characterisation of how coherently the system's units coordinate toward a shared purpose.\n\nThe theoretical foundation is developed in full in the companion paper:\n\n\u003e *Wind Tunnel: A Global Self-Consistency Framework for Software Correctness*\n\u003e `publications/windtunnel-code-testing/windtunnel-code-testing.tex`\n\n---\n\n## Core concepts\n\n**Semantic entropy S ∈ [0, Σ]** — a scalar measuring the residual distance between the system's current state and purposeful operation. S has a positive floor S_flat \u003e 0 (Floor Positivity axiom): a system that is working correctly still carries irreducible uncertainty; the floor is not zero.\n\n**Action-cell C\\*** — the positive-volume region in outcome space where S = S_flat. Correctness is not a point; it is a region. All states inside C\\* are indistinguishable by S.\n\n**Holonomy hol(c, x) = ‖T_c(x) − T_c^spec(x)‖** — the deviation of a directed cycle's actual transformation from its declared specification. Nonzero holonomy on any cycle implies global semantic incorrectness (Cycle Inconsistency Theorem). Zero holonomy is necessary but not sufficient.\n\n**Ensemble order parameter R_ens ∈ [0, 1]** — phase coherence across the dependency graph, derived from Kuramoto coupling theory. Five regimes:\n\n| R_ens | Regime |\n|---|---|\n| \u003c 0.30 | Turbulent — no shared action-cell |\n| 0.30 – 0.50 | Aperture-dominated — interface contracts without shared purpose |\n| 0.50 – 0.80 | Hierarchical cascade — coherent sub-ensembles, incoherent interfaces |\n| 0.80 – 0.95 | Coherent — converging toward a common action-cell |\n| ≥ 0.95 | Phase-locked — partition extinction, coordination friction = 0 |\n\n**Contribution score δS(u, E)** — the reduction in the ensemble's semantic floor when unit u is included. A unit with δS = 0 is *purposeless*: its removal does not change what the ensemble can achieve.\n\n---\n\n## Protocol\n\nThe tool runs in two phases.\n\n**Static phase** (no running system required). Reads the dependency graph and unit type signatures via the `purpose` index. Computes synchronisation tension on each edge, estimates R_est, classifies the coordination regime, identifies decoherence zones (subgraphs whose local R_est falls below the global average), and enumerates directed cycles whose static residuals suggest likely holonomy violations.\n\n**Dynamic phase** (requires runtime traces). Runs the system under representative load. Measures R_dyn(t) as a time series, detects live holonomy violations on candidate cycles, and checks for aperture drift (units whose runtime outputs exit their declared type sets). Computes contribution scores by ablation.\n\nPrimary output: `WT(E, Λ) = (R_dyn, S_flat_est, H, D, δS)` — a regime map, not a verdict.\n\n---\n\n## Dependencies\n\n| Dependency | Purpose |\n|---|---|\n| Rust ≥ 1.75 | All five library crates and the `wt` binary |\n| [`purpose`](https://github.com/fullscreen-triangle/purpose) | Builds a symbol index for the target project; `wt-graph` queries it to extract unit type signatures without reading source files |\n| Python ≥ 3.10 + matplotlib + numpy | Validation suite and figure generation only — not required for `wt` itself |\n\n---\n\n## Installation\n\n```sh\n# 1. Install the purpose indexer\ncargo install --git https://github.com/fullscreen-triangle/purpose\n\n# 2. Clone and build wind-tunnel\ngit clone \u003cthis-repo\u003e\ncd wind-tunnel\ncargo build --release\n\n# The binary is at target/release/wt\n# Optionally install it:\ncargo install --path wt\n```\n\n---\n\n## Usage\n\n### Static analysis only (no traces needed)\n\n```sh\n# Index the target project first\ncd /path/to/your/project\npurpose index\n\n# Run the static phase\nwt static /path/to/your/project\n```\n\nOutput:\n\n```\nRegime        : Hierarchical cascade\nR_est         : 0.6143\nK_c estimate  : 0.8821\nDecoherence zones: 2\nCycle candidates : 1\n  [\"payments\", \"ledger\", \"reconciler\"]  residual=2.3401\n```\n\n### Full protocol (with runtime traces)\n\nTraces are JSONL files, one per unit, placed in a directory. Each line is a JSON object `{\"t\": \u003cfloat\u003e, \"state\": [\u003cfloat\u003e, ...]}`. The filename stem is the unit id.\n\n```sh\n# Run your system under load and collect traces into /tmp/traces/\n# (see docs/trace-format.md for the schema)\n\nwt run /path/to/your/project /tmp/traces/\n```\n\nOutput: `wt-output.json` in the project directory, plus a coloured terminal regime map.\n\n### Re-render a saved result\n\n```sh\nwt report wt-output.json\n```\n\n### Machine-readable output\n\nAll subcommands accept `--json`:\n\n```sh\nwt static /path/to/project --json | jq '.regime'\n```\n\n### Flags\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--json` | off | Emit JSON instead of human-readable output |\n| `--cycle-depth N` | 12 | Maximum cycle length for Johnson's algorithm |\n| `--threshold T` | 0.5 | Static residual threshold for cycle candidates |\n| `--tol T` | 1e-6 | Holonomy violation tolerance |\n| `--dt T` | 0.1 | Time step for R_dyn time series |\n| `--alpha A` | 0.05 | Significance level for purposelessness detection |\n\n---\n\n## Working with the graph directly\n\nIf `purpose index` has already been run on the target project, `wt-graph.json` can be written manually or generated and cached:\n\n```sh\n# Generate and cache the graph (skips purpose queries on subsequent runs)\nwt static /path/to/project --json \u003e /dev/null\n# wt writes wt-graph.json to the project dir on first run\n```\n\nOn subsequent runs, `wt` reads `wt-graph.json` directly without re-querying `purpose`.\n\n---\n\n## Repository layout\n\n```\nwind-tunnel/\n├── Cargo.toml                          workspace root\n├── crates/\n│   ├── wt-graph/                       data model, cycle enumeration, purpose bridge\n│   ├── wt-static/                      Phase 1: tension, R_est, decoherence zones\n│   ├── wt-dynamic/                     Phase 2: traces, holonomy, R_dyn\n│   ├── wt-purpose/                     Phase 3: contribution scores, purposelessness\n│   └── wt-report/                      WindTunnelMetric assembly and rendering\n├── wt/                                 CLI binary\n├── src/\n│   ├── validation.py                   25-experiment numerical validation suite\n│   ├── panels.py                       publication figure generator\n│   └── validation_results.json         25/25 PASS, max error 1.11e-16\n├── docs/\n│   ├── implementation.md               implementation plan (strike-through = done)\n│   └── sources/                        foundational papers (read-only)\n└── publications/\n    └── windtunnel-code-testing/\n        ├── windtunnel-code-testing.tex  companion paper\n        ├── references.bib\n        └── figures/                    panel_{1..5}.png + captions\n```\n\n---\n\n## Validation\n\nAll theorems in the companion paper are numerically validated:\n\n```sh\npython src/validation.py\n```\n\n```\n25/25 PASS\nmax relative error: 1.11e-16\n```\n\nExperiments cover: S-functional axioms, action-cell geometry, Local Invisibility witness, No Template pigeonhole bound, cycle holonomy accumulation, DAG boundary conditions, Kuramoto dynamics across all five regimes, Partition Extinction discontinuity, synchronisation tension decomposition, static R_est, decoherence zone detection, and contribution score computation.\n\n---\n\n## Running the test suite\n\n```sh\ncargo test --workspace\n```\n\n23 unit tests across all five library crates. No external services required.\n\n---\n\n## Theoretical background\n\nThe framework draws on:\n\n- Kuramoto (1975, 1984) — coupled oscillator synchronisation and the critical coupling K_c = 2σ_ω/π\n- Landau (1937) — second-order phase transitions; the Coherent → Phase-locked transition is discontinuous\n- Banach (1922) — fixed-point theorem used in the Purpose Existence proof\n- Kirchhoff (1847) — circuit analogy for constraint cycles\n- Johnson (1975) — elementary cycle enumeration algorithm used in `wt-graph`\n\nThe full bibliography is in `publications/windtunnel-code-testing/references.bib`.\n\n---\n\n## Limitations\n\n**Holonomy requires a cycle specification.** The dynamic phase measures `‖T_c(x) − T_c^spec(x)‖`. The specification function `T_c^spec` must be supplied by the user for each candidate cycle. Without it, the tool defaults to the identity (the cycle should return to its initial state), which is incorrect for stateful loops.\n\n**Contribution scores require ablation runs.** Computing δS(u, E) requires re-running the system without unit u. For large ensembles this is O(n) runs. The static phase provides a regime map without this cost.\n\n**Phase estimation is a proxy.** The `ScalarPhaseEstimator` maps the first state dimension to [0, 2π). For units whose state is not naturally periodic, the estimated R_dyn is a rough indicator, not a precise measurement. Custom estimators can be plugged in via the `PhaseEstimator` trait.\n\n**The action-cell parameters (centre, radius, beta) are domain-specific.** The tool cannot infer them from traces alone. They must be provided by the caller or approximated from the centroid of terminus states.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullscreen-triangle%2Fwind-tunnel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffullscreen-triangle%2Fwind-tunnel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullscreen-triangle%2Fwind-tunnel/lists"}