This repository holds FunnelScript's research contracts, falsifiable hypotheses, architecture decisions, evaluations, and manuscripts. The application repository owns the compiler, interpreter, CLI, tests, packaged Standard Library, and Web Studio.
| Path | Purpose |
|---|---|
spec/ |
Language and execution contracts, hypotheses, grammar, JSON Schema |
evals/ |
Observations and falsification evidence against the specifications |
paper/ |
Academic manuscript and references; claims need independent evidence |
notebooks/ |
Research notebooks and exploratory calculations |
docs/ |
Strategy and ecosystem proposals, not necessarily shipped features |
DECISIONS.md |
Accepted architecture decisions |
DEBATES.md |
Open trade-offs and counterarguments |
OUT_OF_THE_BOX.md |
Speculative ideas requiring evaluation |
- Cite a theoretical or observed anchor. Distinguish proposed mechanisms from implemented capabilities and experimentally validated results.
- State a falsifiable hypothesis, a counterexample, and the invariant or acceptance criterion in the relevant file under
spec/. - Record the test procedure and actual outcomes under
evals/. Link a concrete application test or GitHub Actions run when the claim depends on implementation. - Update the accepted decision, debate, and hypothesis records if the design boundary changes. Keep the research and application documentation aligned.
- Run the same full research test suite as CI and verify the diff before submitting:
python3 -m pytest -q
git diff --checkpytest is required for the full research regression suite, including the documentation-link contracts and other research oracles. python3 -m unittest discover -s tests -v is an optional narrower smoke check only. These tests do not verify external URLs, scientific claims, or the behavior of the application. Research tests require pytest; application dependencies are not installed in this repository.
Work on parsers, World rules, CLI, Python regressions, or Bun belongs in funnelscript/funnelscript. Follow its contributor guide and local AGENTS.md. Reference the relevant research hypothesis and then run the application's own verification suite there. Do not run uv run pytest or bun test as if the research checkout contained the implementation.
- Use English for tracked research and implementation files.
- Do not label a simulation reproducible merely because it produces a fixed seed. Separate model assumptions, fitted data, uncertainty, and out-of-sample validation.
- Report failed hypotheses and reproducible failure lessons; do not alter tests or benchmarks just to obtain a passing result.
- Do not publish credentials, confidential market data, unverifiable financial returns, or predictions disguised as measurements.