Ocarina — manual

00.01 — Ecosystem cartography

Wed, 20 May 2026 00:00:00 +0000

00.01 — Ecosystem cartography#

The Ocarina ecosystem is six public repos under the mojo-molotov GitHub account. They cover five distinct roles:

Role	Repo	Form
Framework	`ocarina`	Python library on PyPI
Public System Under Test (SUT)	`igoristan`	React + Vike SPA, GitHub Pages
Coordination backend	`tests-workers`	Vercel Edge API + Upstash Redis
Example suites	`ocarina-example` (canonical), `ocarina-with-ai-example` (AI)	Python e2e suites driving Igoristan / CURA
Public documentation	`ocarina-holy-book`	VitePress site (EN + FR + RU), PDFs, AI skills

The big picture#

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              OCARINA (BIG PICTURE)                              │
└─────────────────────────────────────────────────────────────────────────────────┘

   ┌──────────────────────────────┐         ┌──────────────────────────────────┐
   │  [PACKAGE]  ocarina          │ ──────► │  [PACKAGE]  ocarina-example      │
   │  Python framework 3.14+      │   pip   │  e2e suite against the Igoristan │
   │  ROP / DSL / orchestration   │ install │  (Selenium + Firefox + Redis)    │
   └──────────────────────────────┘         └──────────────────────────────────┘
            │  │                                       │  ▲   │
            │  │                                       │  │  uses
            │  │ pip install ocarina                   │  │  IGOR_API_KEY
            │  ▼                                       ▼  │   │
            │  ┌────────────────────────────────────┐  drives │
            │  │ [PACKAGE]  ocarina-with-ai-example │  ┌──────┴──────────────────┐
            │  │ e2e suite against CURA Healthcare  │  │ [WEBSITE]  igoristan    │
            │  │ Claude Code, 99% machine-written   │  │ React 19 + Vike         │
            │  └────────────────────────────────────┘  │ GitHub Pages            │
            │              │                           └──────┬──────────────────┘
            │              │ drives                           │ fetches OTP
            │              ▼                                  ▼
            │   ┌──────────────────────────────┐    ┌──────────────────────────────┐
            │   │ [WEBSITE]  CURA Healthcare   │    │ [BACKEND]  tests-workers     │
            │   │ Heroku, open-source PHP      │    │ Vercel Edge Functions        │
            │   └──────────────────────────────┘    │ + Upstash Redis              │
            │                                       │ /api/otp, /otp-history,      │
            │                                       │ /api/corsicadex              │
            │                                       └──────────────────────────────┘
            │                                                 ▲
            │                                                 │ x-api-key
            │                                                 │ (IGOR_API_KEY ≡ API_SECRET)
            │                                                 │
            ▼
   ┌──────────────────────────────┐
   │  [DOCS]  ocarina-holy-book   │
   │  VitePress EN + FR + RU      │
   │  AI skills, PDFs, llms.txt   │
   │  GitHub Pages                │
   └──────────────────────────────┘

ocarina → example suites: plain pip dependency (pip install ocarina).
Example suites → SUT (Igoristan / CURA): browser automation through Selenium.
Igoristan suite ↔ tests-workers: HTTP calls (OTP, Corsicadex). Shared secret: IGOR_API_KEY client-side ≡ API_SECRET server-side.

Responsibilities#

Role	Contract	Constraint
Framework	Ships the DSL, the orchestration, the driver pool, the reporters	Stays small, auditable, no hidden deps
Public SUT	A deliberately chaotic playground (random errors, OTP, finicky forms)	Lives on GitHub Pages forever, no heavy backend
Coordination backend	Coordinates workers on OTP, surfaces data for parallel tests	Stateless code, state in Redis (Upstash)
Example suites	Show how Ocarina actually gets used — without AI (canonical) and with AI (CURA)	Public, runnable, complete, in CI
Documentation	The why, the how, and the AI part	EN + FR + RU (Corso-Russian tradition), LLM-friendly files like `llms.txt`, plus PDFs

Three licenses#

License	Where	Why
MIT	`ocarina`, `ocarina-example`, `ocarina-with-ai-example`, `ocarina-holy-book`	Python code or docs. Transmissible as-is. Sovereign. See `../11-independence/`.
ISC	`tests-workers`	Vercel Edge scaffold default. Kept as-is.
(unlicensed)	`igoristan`	Public demo app. Treat it as WTFPL.

Deliberate friction between repos#

The design is intentionally asymmetric along certain axes. The friction is the testing tool:

01.01 — Flipping the problem

Wed, 20 May 2026 00:00:00 +0000

01.01 — Flipping the problem#

The observation#

Every modern e2e testing framework was built on one implicit assumption: there’s a barrier between people who code and people who define tests. That barrier gets taken for granted — methodologically, organizationally, sometimes contractually.

Most testing frameworks were built in a world where the barrier between “those who code” and “those who define tests” was real and structural.

The two historic answers to that assumption show up in the Holy Book:

02.01 — Ocarina's technical identity

Wed, 20 May 2026 00:00:00 +0000

02.01 — Ocarina’s technical identity#

`pyproject.toml`#

[project]
name = "ocarina"
version = "1.1.10"
description = "Websites test framework for Igor"
requires-python = ">=3.14"
authors = [{ name="Igor Casanova", email="[REDACTED]" }]
license = "MIT"
license-files = ["LICEN[CS]E*"]
readme = "README.md"

dependencies = ["python-docx>=1.2.0"]

version = "1.1.10": stable 1.x, not a pre-release.
requires-python = ">=3.14": PEP 695 generic typing everywhere.
dependencies = ["python-docx>=1.2.0"]: one runtime dependency. The rest lives in dev.
license = "MIT".
description = "Websites test framework for Igor": not “for everyone,” not “for humans,” explicitly “for Igor.” Lines up with ../01-philosophy/05-political-stance.md: “It’s my car.”

`dev` dependencies#

[dependency-groups]
dev = [
    "ruff>=0.15.0",
    "mypy>=1.17.0",
    "mypy-extensions>=1.1.0",
    "typing-extensions>=4.14.0",
    "pytest>=9.0.0",
    "pytest-cov>=7.0.0",
    "hypothesis>=6.151.0",
    "pytest-mypy-plugins>=3.1.0",
    "allure-pytest>=2.15.3",
    "allure-python-commons>=2.15.3",
    "pre-commit>=4.5.1",
    "syrupy>=5.1.0",
    "selenium>=4.40.0",
    "playwright>=1.60.0",
    "twine>=6.2.0",
    "build>=1.4.2",
    "prysk>=0.20.0",
]

Tool	Role in Ocarina
`ruff`	Linter + formatter (replaces flake8 + isort + black). `select = ["ALL"]`.
`mypy` (+ extensions)	Type-checker. `strict = true` (see `mypy.ini`).
`pytest`	Unit-test runner (the framework is itself tested).
`pytest-cov`	Test coverage (of the framework itself). Configured in `pyproject.toml#tool.coverage`.
`hypothesis`	Property-based testing (PBT) → `test_invariants_properties.py`.
`pytest-mypy-plugins`	Static typing tests (checks expected mypy errors and type-inference tests with `reveal_type`).
`allure-pytest` / `allure-python-commons`	Allure report (deployed to GH Pages).
`pre-commit`	Local git hooks (ruff-format).
`syrupy`	Snapshot testing (output of `pretty_print_results`, `results_to_json`).
`selenium`	Present in `dev` because Ocarina doesn’t depend on Selenium to work; it just ships a Selenium adapter so the framework is immediately operational out of box.
`playwright`	Same logic: a second shipped adapter (since `1.1.3`). Ocarina now drives both Selenium and Playwright out of the box, behind the same ports.
`twine` / `build`	PyPI publishing.
`prysk`	CLI tests in the cram (`.t`) format. Successor to `cram`.

`mypy.ini`#

[mypy]
python_version = 3.14
strict = true

# * ... Allow missing annotations (type inference is cool)
disallow_incomplete_defs = false

# * ... Allow missing annotations (type inference is cool)
disallow_untyped_defs = false

strict = true: enables --warn-redundant-casts, --warn-unused-ignores, --no-implicit-optional, --check-untyped-defs, etc.
Two exceptions: disallow_incomplete_defs and disallow_untyped_defs are off. mypy’s type inference is good enough when explicit annotations don’t add value. Annotations live where they actually matter.

`pyproject.toml#tool.ruff`#

[tool.ruff.lint]
select = ["ALL"]
ignore = [
    "ANN002", "ANN003", "ANN201",
    "TRY003",
    "C901",
    "D203",    # conflict with D211
    "D213",    # conflict with D212
    "COM812",  # conflict with the ruff formatter (auto-fix)
]

[tool.ruff]
exclude = ["**/.venv/**", "**/bin/**", "**/__init__.py", "**/__bypass_linter__"]

select = ["ALL"]: every ruff rule on (~800).
Short ignore list: six rules, each one justified.
B008 must NEVER be ignored ("# "B008", # * ... NEVER ignore this rule without knowing very well what you are doing: https://docs.astral.sh/ruff/rules/function-call-in-default-argument/"). Note left so the past mistake doesn’t repeat.
****/**bypass_linter****: directory convention for explicitly un-linted code (handy for internal experimental modules).

`pyproject.toml#tool.pytest.ini_options`#

testpaths = ["tests"]
python_files = ["test_*.py"]
norecursedirs = [".*", "__pycache__"]
log_cli = true
log_cli_level = "DEBUG"
log_cli_format = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
log_cli_date_format = "%Y-%m-%d %H:%M:%S"
addopts = """
--cov=src
--cov-branch
--cov-report=term-missing
--cov-report=html
--cov-report=xml:coverage.xml
"""

Setting	Effect
`log_cli = true`	All test logs surface in the CLI (useful for scenarios that go through `ILogger`).
`--cov=src` + `--cov-branch`	Branch coverage, not just line coverage.
`--cov-report=html` + `xml`	Three outputs: terminal, local HTML, XML for CI ingestion.

`pyproject.toml#tool.coverage`#

Full detail at ../04-internal-tests/07-coverage-policy.md. Short version: anything that’s pure shape (custom_types, ports, errors), anything that needs a real browser (Selenium adapters), and anything covered by cram tests (cli/store, cli/builder) is explicitly omitted. Otherwise the metrics lie.

02.03.01 — The Result[T] type

Wed, 20 May 2026 00:00:00 +0000

02.03.01 — The `Result[T]` type#

Source file: src/ocarina/railway/result.py — zero dependencies.

Code#

from dataclasses import dataclass, field
from typing import TypeGuard, final


class _BaseResult:
    """Base class ensuring both Ok and Fail have error attribute for type narrowing."""
    error: Exception | None


@final
@dataclass(frozen=True)
class Ok[T](_BaseResult):
    value: T
    error: None = None


@final
@dataclass(frozen=True)
class Fail(_BaseResult):
    error: Exception = field(default_factory=lambda: Exception("Unknown error"))


type Result[T] = Ok[T] | Fail


def is_ok[T](result: Result[T]) -> TypeGuard[Ok[T]]:
    return isinstance(result, Ok)


def is_fail[T](result: Result[T]) -> TypeGuard[Fail]:
    return isinstance(result, Fail)

Six design decisions, dissected#

1. `_BaseResult` as a common parent#

class _BaseResult:
    error: Exception | None

One job: let mypy read result.error without narrowing first. Without the base, you’d have to write:

02.04.01 — The validate → assert_that → execute → raise_if_invalid flow

Wed, 20 May 2026 00:00:00 +0000

02.04.01 — The `validate → assert_that → execute → raise_if_invalid` flow#

Source file: src/ocarina/dsl/invariants/validate.py (entry-point) + src/ocarina/dsl/invariants/internals/validation_chain.py

The state machine#

Diagram#

validate(value: T)
       │
       ▼
ValidationStartBlock[T]
       │
       └─ assert_that(predicate, *, msg=None)
              │
              ▼
       ValidationAssertBlock[T]   ← state accepting several continuations
              │
              ├─► assert_that(P)     [loop, AND-chainable, see dedicated diagram]
              ├─► otherwise(P)       [OR, see 03-otherwise-any-of.md]
              ├─► then(U, name=...)  [value swap, see 04-then-chain-of-validations.md]
              └─► execute()          → _ValidationResult
                                          │
                                          ├─ is_valid: bool
                                          ├─ errors: Sequence[InvariantViolationError]
                                          ├─ validated_values: Sequence[Any]
                                          └─ raise_if_invalid() : None | raise AggregateInvariantViolationError

`assert_that` loop#

assert_that declares one assertion on the current value. Multiple assert_that calls chain — each adds another condition (logical AND, order preserved).

02.05.01 — Test[Driver]

Wed, 20 May 2026 00:00:00 +0000

02.05.01 — `Test[Driver]`#

Source file: src/ocarina/dsl/testing/oc_test.py

Signature#

@final
class Test[Driver]:
    def __init__(
        self,
        *,
        name: TestName,
        test_id: str | None = None,
        test_scenario: TestScenario[Driver],
        pre_test_scenarios_fragments: Sequence[TestScenarioFragment[Driver]] | None = None,
        post_test_scenarios_fragments: Sequence[TestScenarioFragment[Driver]] | None = None,
        skipped: bool = False,
    ) -> None:
        if test_id is None:
            test_id = name
        self.name = name
        self.test_id = test_id
        self._test_scenario = test_scenario
        self._pre_test_scenarios_fragments = pre_test_scenarios_fragments or []
        self._post_test_scenarios_fragments = post_test_scenarios_fragments or []
        self._skipped = skipped

Six parameters:

Parameter	Type	Role
`name`	`TestName` (`str`)	Human label; appears in the report, and becomes the log file name (hence subject to `is_valid_filename`).
`test_id`	`str \| None`	Stable identifier for `--only` / `--exclude`. If absent: takes `name`.
`test_scenario`	`TestScenario[Driver]` (alias = `Callable[[Driver, ILogger], Scenario[Driver]]`)	Factory that builds the `Scenario` at execution time.
`pre_test_scenarios_fragments`	`Sequence[TestScenarioFragment[Driver]] \| None`	`(driver, logger) -> TestChain` functions executed before the main scenario.
`post_test_scenarios_fragments`	`Sequence[TestScenarioFragment[Driver]] \| None`	`(driver, logger) -> TestChain` functions executed after the main scenario.
`skipped`	`bool`	If `True`, the test is registered but not executed.

1. `@final`#

No user inheritance. Want a “special” test? Compose via fragments or a scenario — don’t subclass.

02.10.01 — WebDriversPool[Driver]

Wed, 20 May 2026 00:00:00 +0000

02.10.01 — `WebDriversPool[Driver]`#

Source file: src/ocarina/infra/drivers_pool.py

Thread-safe driver pool, max concurrency enforced by semaphore, monitored async warmup, clean shutdown. No reuse — every acquire() disposes its driver on the way out (clean state).

Constructor#

@final
class WebDriversPool[Driver]:
    def __init__(
        self,
        create_driver: Thunk[BuiltWebDriver[Driver]],
        max_size: int,
        warmup_timeout: float | None = None,
    ) -> None:
        self._create_driver = create_driver
        self._pool: Queue[BuiltWebDriver[Driver]] = Queue(max_size)
        self._semaphore = Semaphore(max_size)
        self._warmup_timeout = (
            warmup_timeout if warmup_timeout is not None and warmup_timeout > 0.1
            else 60.0 * 5
        )

Primitive	Role
`Queue(max_size)`	Queue of pre-built available drivers.
`Semaphore(max_size)`	Guarantees that at most `max_size` drivers live simultaneously (whether queued or acquired).
`warmup_timeout`	Max no-progress delay during warmup before raising `WarmupTimeoutError`. Default 300s.

`acquire()`#

@contextmanager
def acquire(self) -> Iterator[Driver]:
    try:
        driver, dispose = self._pool.get_nowait()
    except Empty:
        self._semaphore.acquire()
        try:
            driver, dispose = self._create_driver()
        except Exception:
            self._semaphore.release()
            raise

    try:
        yield driver
    finally:
        with suppress(Exception):
            dispose()
        self._semaphore.release()

              acquire()
                  │
                  ▼
   ┌──────────────────────────────────┐
   │ pool.get_nowait()                │── OK ─► driver, dispose         ← warmup case
   └──────────────┬───────────────────┘
                  │ Empty
                  ▼
   ┌──────────────────────────────────┐
   │ sem.acquire()                    │  ← blocks if N drivers alive
   └──────────────┬───────────────────┘
                  ▼
   ┌──────────────────────────────────┐
   │ create_driver()                  │── raises ─► sem.release(); raise
   └──────────────┬───────────────────┘
                  ▼
   ┌──────────────────────────────────┐
   │ yield driver                     │  ← caller uses it
   └──────────────┬───────────────────┘
                  ▼
                finally :
                  with suppress : dispose()       ← driver disposed
                  sem.release()                   ← release a slot

1. No reuse#

Queue.get_nowait() consumes the entry. Once pulled, the driver never goes back. At the end (finally), it’s disposed.

02.11.01 — CliBuilder + CliArg + _SilentArgumentParser

Wed, 20 May 2026 00:00:00 +0000

02.11.01 — `CliBuilder` + `CliArg` + `_SilentArgumentParser`#

Source file: src/ocarina/opinionated/cli/builder.py

Declarative overlay on top of argparse. Aggregates validation errors, rewrites the help output on error, and registers post-parse effects.

`_SilentArgumentParser`#

class _SilentArgumentParser(ArgumentParser):
    def error(self, message: str) -> Never:
        """Raise an error."""
        raise ValueError(message)

The standard ArgumentParser calls sys.exit(2) directly on error. With that turd of a default, you can’t intercept and you can’t aggregate multiple errors.

_SilentArgumentParser reroutes errors as ValueError. So CliBuilder.parse can catch and aggregate them.

03.01 — Effect, Thunk[T], Result[T]

Wed, 20 May 2026 00:00:00 +0000

03.01 — `Effect`, `Thunk[T]`, `Result[T]`#

Three lines in custom_types/ + one in railway/. The whole DSL rides on them.

Triplet#

# src/ocarina/custom_types/effect.py
type Effect = Callable[[], None]
type Effects = tuple[Effect, ...]

# src/ocarina/custom_types/thunk.py
type Thunk[T] = Callable[[], T]

# src/ocarina/railway/result.py
type Result[T] = Ok[T] | Fail

Type	FP semantics	Definition
`Effect`	Side effect (deferred)	`() -> None`
`Thunk[T]`	Deferred computation with value	`() -> T` (laziness + value)
`Result[T]`	Computation that can fail	Discriminated union `Ok[T] \| Fail`

Effect vs Thunk distinction#

log_msg: Effect = lambda: print("hello")        # () -> None
get_42: Thunk[int] = lambda: 42                 # () -> int
fetch:  Thunk[Result[int]] = lambda: Ok(42)     # () -> Result[int]

Function returns something consumed elsewhere → Thunk[T].
Otherwise → Effect.

04.01 — From the outside like a user strategy

Wed, 20 May 2026 00:00:00 +0000

04.01 — "From the outside like a user" strategy#

The posture lives in the scenario tests’ conftest.py. No test cheats by peeking at internals.

`tests/scenarios/conftest.py`#

Component	Role
`FakeDriver` (dataclass)	Minimal driver: `title`, `disposed`. No Selenium method.
`make_built_driver()`	Factory `(FakeDriver, dispose)`, i.e. the signature `WebDriversPool` expects.
`make_pool(max_size=2)`	`WebDriversPool[FakeDriver]` ready to go.
`RecordingPOM(POMBase)`	POM that records its calls and can be configured to raise.
`acting(pom, step)`	Full `ActionSuccess[RecordingPOM]` (failure+success as no-ops).
`scenario_of("ok", "ok2")`	`TestScenario[FakeDriver]` with N steps.
`failing_scenario(step="boom", exc=...)`	1-step scenario that raises.
`make_test(name, scenario=..., test_id=..., skipped=False)`	`Test[FakeDriver]`
`make_suite(name, tests, pool=..., transient_errors=..., max_retries_per_test=...)`	`TestSuite[FakeDriver]`
`make_campaign(name, suites, max_workers=1)`	`TestCampaign[FakeDriver]`
`make_cycle(name="cycle", campaigns=..., smoke=..., mode=...)`	`TestCycle[FakeDriver]`
`run_chain(runner)`	Helper that executes a `ChainRunner` and returns the `ActionChain`.

`FakeDriver`#

@dataclass
class FakeDriver:
    title: str = "fake"
    disposed: bool = False

That’s all. Ocarina’s core calls no Selenium API.

05.01 — Igoristan stack

Wed, 20 May 2026 00:00:00 +0000

05.01 — Igoristan stack#

`package.json`#

{
  "react": "^19.2.3",
  "react-dom": "^19.2.3",
  "vike": "^0.4.258",
  "vike-react": "^0.6.21",
  "valibot": "^1.2.0",
  "react-hook-form": "^7.71.1",
  "@hookform/resolvers": "^5.2.2",
  "react-dropzone": "^14.3.8",
  "lucide-react": "^0.562.0",
  "usehooks-ts": "^3.1.1",
  "throttleit": "^2.1.0",
  "uuid": "^13.0.0",
  "clsx": "^2.1.1",
  "class-variance-authority": "^0.7.1",
  "tailwind-merge": "^3.0.2",
  "tailwindcss-animate": "^1.0.7",
  "@radix-ui/react-slot": "^1.2.4"
}

Lib	Role
React 19.2	UI, hooks
Vike 0.4 + `vike-react`	SSG / SSR framework on top of Vite (formerly “vite-plugin-ssr”)
Valibot 1.2	TS schema validation (lightweight Zod alternative)
react-hook-form	Form handling
react-dropzone	Drag-and-drop upload component
lucide-react	Icons
usehooks-ts	Utility hooks (`useLocalStorage`, etc.), used by `useAuth`
throttleit	Throttle
uuid	ID generation
clsx + tailwind-merge + class-variance-authority	Tailwind utilities

`devDependencies`#

{
  "vite": "^7.3.1",
  "@vitejs/plugin-react": "^5.1.2",
  "@tailwindcss/vite": "^4.1.3",
  "@tailwindcss/postcss": "^4.0.17",
  "tailwindcss": "^4.1.1",
  "terser": "^5.39.0",
  "vite-plugin-compression": "^0.5.1",
  "rollup-plugin-visualizer": "^5.14.0",
  "@qalisa/vike-plugin-sitemap": "^1.7.0",

  "typescript": "^6.0.3",
  "typescript-eslint": "^8.59.0",
  "eslint": "^9.18.0",
  "@eslint/js": "^9.39.2",
  "eslint-plugin-import-x": "^4.6.1",
  "eslint-plugin-perfectionist": "^4.6.0",
  "eslint-plugin-react": "^7.37.4",
  "eslint-plugin-react-hooks": "^5.2.0",
  "eslint-plugin-unused-imports": "^4.2.1",
  "globals": "^15.15.0",

  "prettier": "^3.5.3",
  "prettier-plugin-tailwindcss": "^0.6.11",

  "husky": "^9.1.7",
  "lint-staged": "^15.5.0",
  "commitizen": "^4.3.1",
  "@commitlint/config-conventional": "^19.8.0",
  "@commitlint/cz-commitlint": "^19.8.0",
  "is-ci": "^4.1.0",
  "editorconfig": "^2.0.1",
  "minimatch": "^10.1.1",
  "rimraf": "^6.0.1",
  "wireit": "^0.14.11"
}

`engines`#

{
  "node": "^24.x",
  "pnpm": "11.x"
}

→ Node 24, pnpm 11. packageManager: pnpm@11.x locks the version.

06.01 — Vercel Edge stack

Wed, 20 May 2026 00:00:00 +0000

06.01 — Vercel Edge stack#

`package.json`#

{
  "name": "tests-workers",
  "version": "1.0.0",
  "scripts": {
    "vercel-build": "echo 'Build skipped'"
  },
  "packageManager": "pnpm@11.2.2",
  "dependencies": {
    "@upstash/redis": "^1.36.2",
    "otplib": "^13.2.1"
  },
  "devDependencies": {
    "@types/node": "^25.2.0",
    "next": "^16.1.6",
    "@vercel/node": "^5.5.28",
    "typescript": "^5.9.3"
  },
  "license": "ISC"
}

Lib	Role
`@upstash/redis` (runtime)	REST Redis client (no TCP). Edge-compatible.
`otplib` (runtime)	RFC 6238 TOTP generation.
`next` (dev only)	Types only (`NextRequest`). No Next.js app.
`@vercel/node` (dev only)	Vercel types.
`@types/node` (dev only)	Node 22+ types.

No runtime dependency beyond @upstash/redis + otplib. Bundle is microscopic → cold start < 100ms.

07.01 — Tree

Wed, 20 May 2026 00:00:00 +0000

07.01 — Tree#

src/
├── main.py                                                     # entry point (see README)
│
├── api/                                                        # external HTTP clients
│   ├── retrieve_dashboard_otp_code.py                          # filter + sort + pick OTP
│   ├── get_otp_history.py                                      # HTTP GET /api/otp-history
│   └── constants/endpoints.py                                  # URLs of tests-workers endpoints
│
├── caches/                                                     # in-memory L1 cache
│   ├── l1.py                                                   # dogpile.cache.memory TTL 30m
│   └── reserve_free_cache_key.py                               # UUID + threading.Lock
│
├── constants/                                                  # constants
│   ├── pages/
│   │   ├── homepage.py                                         # HOMEPAGE_URL
│   │   ├── dashboard.py                                        # DASHBOARD_URL + input ids
│   │   ├── random_loaders.py
│   │   ├── sacred_upload.py
│   │   ├── corsicamon.py
│   │   ├── chaotic_form.py
│   │   ├── madness.py
│   │   ├── random_error_page.py
│   │   └── donkey_sausage_eater_detector.py
│   └── sys/
│       ├── redis_keys.py                                       # OTP_SEND_LOCK_KEY, ...
│       └── transient_errors.py                                 # (WebDriverException, HttpError...)
│
├── lib/
│   ├── connectors/test_steps/actions/                          # functions (TPOM) -> TPOM
│   │   ├── homepage.py
│   │   ├── dashboard_login.py                                  # ~10 connectors (with/without retries)
│   │   ├── dashboard_welcome.py
│   │   ├── dashboard_protected_page.py
│   │   ├── sacred_upload.py
│   │   ├── corsicamon_enter_api_key.py
│   │   ├── corsicamon_main.py
│   │   ├── chaotic_form.py
│   │   ├── random_error.py
│   │   ├── random_loaders.py
│   │   ├── madness.py
│   │   ├── this_is_bastia.py
│   │   ├── cors_errors.py
│   │   ├── bsod.py
│   │   ├── dsed.py
│   │   └── ids_bypassed.py
│   ├── custom_errors/
│   │   ├── http.py                                             # HttpErrorPageReachedError
│   │   └── transient_error.py                                  # TransientError
│   └── ext/                                                    # extensions / adapters
│       ├── ocarina/
│       │   ├── adapters/
│       │   │   ├── agnostic/
│       │   │   │   ├── act.py                                  # ⭐ act adapter (on_failure hook)
│       │   │   │   ├── env_getters.py                          # ⭐ typed EnvGetters adapter
│       │   │   │   └── match_page.py                           # ⭐ match_page adapter
│       │   │   └── selenium/
│       │   │       ├── test_suite.py                           # ⭐ TestSuite adapter
│       │   │       ├── test_campaign.py                        # ⭐ TestCampaign adapter
│       │   │       ├── cli_getters.py                          # typed getters from CliStore
│       │   │       ├── logs.py                                 # create_just_log_error, etc.
│       │   │       └── screenshotter.py                        # take_screenshot helper
│       │   └── regex/error_page.py                             # ERROR_PAGE_REGEX
│       ├── redis/
│       │   └── client.py                                       # Redis Singleton client
│       └── selenium/
│           ├── humanize/                                       # ⭐ HumanizedDriver + keyboard
│           │   ├── proxy.py
│           │   └── keyboard.py
│           ├── pages/verify_elements_presence.py
│           └── watchers/catch_me_if_you_can_watcher.py         # ⭐ Watcher callback
│
├── pages/                                                      # POMs (Selenium + SeleniumTitleMixin)
│   ├── homepage.py
│   ├── random_loaders.py
│   ├── chaotic_form.py
│   ├── random_error.py
│   ├── sacred_upload/
│   │   ├── sacred_upload.py
│   │   └── fixtures/                                           # files to upload
│   ├── dashboard/
│   │   ├── login.py                                            # ⭐ with OTP, retries, redis locks
│   │   ├── welcome_page.py
│   │   └── protected_page.py
│   ├── corsicamon/
│   │   ├── enter_api_key.py
│   │   └── main.py
│   ├── madness/
│   │   ├── base.py
│   │   ├── matchers.py                                         # has_cors, has_this_is_bastia
│   │   ├── cors.py
│   │   └── this_is_bastia.py
│   └── donkey_sausage_detector/
│       └── ids_bypassed.py
│
└── tests/
    ├── cycles/e2e.py                                           # ⭐ TestCycle (smoke + main)
    ├── campaigns/
    │   ├── global_smoke_tests.py                               # smoke
    │   ├── corsicamon.py                                       # main (+ smoke variant)
    │   ├── dashboard_login.py                                  # main
    │   ├── randomness.py                                       # main
    │   └── sacred_upload.py                                    # main
    ├── suites/
    │   ├── global_smoke_tests.py
    │   ├── randomness.py
    │   ├── dashboard/
    │   │   ├── access/
    │   │   │   ├── happy_paths.py
    │   │   │   └── unhappy_paths.py
    │   │   └── data_driven/multi_login.py
    │   ├── sacred_upload/{happy_paths,unhappy_paths}.py
    │   └── corsicamon/{smoke_tests,happy_paths,unhappy_paths}.py
    └── scenarios/
        ├── homepage/verify_homepage.py
        ├── dashboard/
        │   ├── access/{happy_paths,unhappy_paths}.py
        │   ├── back_to_igoristan.py
        │   └── data_driven/{multi_login,datasets/multi_login}.py
        ├── sacred_upload/{upload_files,just_go_back_to_igoristan}.py
        ├── corsicamon/{enter_api_key,new_draw,add_corsicamon,back_to_igoristan}.py
        └── randomness/
            ├── level_1/{random_error_page,random_loaders_page}.py
            ├── level_2/{dsed,madness}.py
            ├── level_3/chaotic_form.py
            └── level_4/walkthrough.py

Folder semantics#

Folder	Role	Convention
`pages/`	POMs (inherit `SeleniumTitleMixin, POMBase`)	One class per page, fluent (`return self`)
`lib/connectors/test_steps/actions/`	Connectors `(TPOM) -> TPOM`	Pure functions; if parameters, closures
`lib/custom_errors/`	Project exceptions	Exception subclasses
`lib/ext/ocarina/adapters/`	Adapters above Ocarina	See `02-adapters.md`
`lib/ext/redis/`	Redis Singleton wrapper	For distributed locks
`lib/ext/selenium/`	Selenium extensions specific to the project	`HumanizedDriver`, `Watcher` callback
`caches/`	In-memory L1 cache	`dogpile.cache.memory` + UUID reservation
`constants/`	Constants	URLs, redis keys, transient errors
`api/`	External HTTP clients	OTP retrieval, OTP history
`tests/`	ISTQB hierarchy	cycles / campaigns / suites / scenarios

`lib/` vs `pages/`#

pages/: POMs — encapsulate a page’s state (locators, action methods).
lib/connectors/test_steps/actions/: connectors — functions that call into POMs.

act(on_homepage, open_homepage)
#                ^^^^^^^^^^^^^
#                connector defined in lib/connectors/test_steps/actions/homepage.py

def open_homepage(p: Homepage) -> Homepage:
    return p.open()

The AI project’s CLAUDE.md enforces this as a discipline:

08.01 — Code: 99% Claude, 1% Igor, intelligence: 50-50

Wed, 20 May 2026 00:00:00 +0000

08.01 — Code: 99% Claude, 1% Igor, intelligence: 50-50#

README#

A note to the reader#

This project is an experiment in AI-driven test engineering. In the interest of honesty about how it was built:

Claude Code Human

Code written 99% 1%

Intelligence 50% 50%

Almost every line was machine-written. The judgement behind it — what to test, what to distrust, when to dig and when to stop — was shared.

	Claude Code	Human
Code written	99%	1%
Intelligence	50%	50%

09.01 — VitePress + Sugar Theme + in-house plugins stack

Wed, 20 May 2026 00:00:00 +0000

09.01 — VitePress + Sugar Theme + in-house plugins stack#

`package.json`#

{
  "dependencies": {
    "@sugarat/theme": "0.5.17"
  },
  "devDependencies": {
    "@commitlint/config-conventional": "20.5.0",
    "@commitlint/cz-commitlint": "20.5.1",
    "@eslint/js": "10.0.1",
    "@types/node": "25.6.0",
    "commitizen": "4.3.1",
    "editorconfig": "3.0.2",
    "eslint": "10.2.1",
    "eslint-plugin-import-x": "4.16.2",
    "eslint-plugin-perfectionist": "5.9.0",
    "eslint-plugin-unused-imports": "4.4.1",
    "globals": "17.5.0",
    "husky": "9.1.7",
    "inquirer": "9.0.0",
    "is-ci": "4.1.0",
    "lint-staged": "16.4.0",
    "pagefind": "1.5.2",
    "prettier": "3.8.3",
    "sass-embedded": "1.99.0",
    "typescript": "6.0.3",
    "typescript-eslint": "8.59.0",
    "vitepress": "2.0.0-alpha.17",
    "vitepress-plugin-image-optimize": "1.5.1",
    "vue": "3.5.33"
  },
  "engines": {
    "node": "^24.x",
    "pnpm": "11.x"
  }
}

Lib	Role
`vitepress 2.0.0-alpha.17`	SSG framework, Vite-based
`@sugarat/theme`	First-class blog theme (templates, auto sidebar, covers)
`vue 3.5.33`	Required by VitePress
`vitepress-plugin-image-optimize`	Build-time image optimization
`pagefind 1.5.2`	Static search engine (full-text, side-CDN)
`sass-embedded`	Compiles SCSS (used by `@sugarat/theme`)
Husky / lint-staged / commitlint	Same tools as the other repos (Conventional Commits)

`docs/.vitepress/config.mts`#

import { defineConfig } from 'vitepress';
import path from 'path';
import fs from 'fs';

import { generateSkills } from './plugins/skills';
import { generateLlms } from './plugins/llm';
import { generatePub } from './plugins/pub';
import { blogTheme } from './blog-theme';
import webpConfig from './plugins/webp';

const base = process.env.GITHUB_ACTIONS === 'true' ? '/ocarina-holy-book/' : '/';

export default defineConfig({
  locales: {
    root: {
      themeConfig: {
        outline: { label: 'Table of content' },
        skipToContentLabel: 'Skip to content',
        sidebarMenuLabel: 'Related articles',
        returnToTopLabel: 'Return to top',
        lastUpdatedText: 'Last update:'
      },
      description: "Ocarina is Igor's automated web browser testing framework.",
      title: 'The Ocarina Holy Book',
      label: 'English',
      lang: 'en'
    },
    fr: {
      themeConfig: {
        outline: { label: 'Sommaire', level: [2, 3] },
        returnToTopLabel: 'Retour en haut de page',
        lastUpdatedText: 'Dernière mise à jour :',
        skipToContentLabel: 'Passer au contenu',
        sidebarMenuLabel: 'Voir aussi'
      },
      title: "Le livre sacré d'Ocarina",
      label: 'Français',
      lang: 'fr'
    }
    ru: {
      themeConfig: {
        outline: {
          label: 'Оглавление',
          level: [2, 3]
        },
        skipToContentLabel: 'Перейти к содержанию',
        lastUpdatedText: 'Последнее обновление:',
        returnToTopLabel: 'Вернуться вверх',
        sidebarMenuLabel: 'Смотрите также'
      },
      title: 'Священная Книга Ocarina',
      label: 'Русский',
      lang: 'ru'
    }
  },
  vite: { ... },
  ...
});

1. `base`#

const base =
  process.env.GITHUB_ACTIONS === "true" ? "/ocarina-holy-book/" : "/";

In CI (GitHub Actions): base = /ocarina-holy-book/ (GitHub Pages prefix). Locally: / (served from the dev server root).

09.03.01 — Review skills

Wed, 20 May 2026 00:00:00 +0000

09.03.01 — Review skills#

Static reads, surface findings. A large family. Lets the AI review its project systematically.

Listing (potentially non-exhaustive)#

Skill	Target
`review-spec-gaps`	Clarification questions on the FRDs
`review-watcher-misuse`	Verifies the “negative-only” principle of `watcher.report(...)`
`review-compartmentalisation-leaks`	Detects URLs, selectors, magic numbers in wrong places
`review-dead-code`	Detects unused connectors / POMs / scenarios / suites / fragments / constants
`review-report`	Classifies each FAIL / SKIP of an execution
`review-type-ignore`	Audits `# type: ignore`s (are they justified?)
`review-match-candidates`	Spots places where a `match` (Python, pattern matching) could be used instead of `if` `elif` `elif` `if` `if` `elif`
`review-unverified-transitions`	Verifies that every page transition has a `verify`
`review-submit-dispatchers`	Audits input-confirmation methods (click vs enter key…)
`review-comment-drift`	Detects comments that have drifted from the code
`review-suite-stability`	Evaluates a suite’s stability (proportion of retries, transient_errors hits)
`review-intent-collisions`	Detects tests that overwrite each other (conflicting intents) and asks/proposes clarifications
`review-watcher-emissions`	Audits watcher emissions (volume, dedup, relevance)
`review-hierarchy-naming`	Audits the test-hierarchy naming (`TestCycle` / `TestCampaign` / `TestSuite` / `Test`) for the lazy-naming antipattern where a child carries the parent’s name

`review-dead-code`#

input  : test base
output : list of unused elements (connectors / POMs / scenarios / fragments / constants)
         + per-element recommendation:
            - delete
            - move to incubator (<root-source>/incubator/, dependency tree preserved)
            - keep (justify)

`review-report`#

input  : a recent execution (logs + reports)
output : per-test classification:
            - PASS                  (nothing to do)
            - SKIP                  (why?)
            - intentional gap FAIL  (G-DATA-*, G-SEC-*, ...)
            - cross-browser FAIL    (B-BROWSER-*)
            - transient FAIL        (A-ENV-*)
            - regression            ⚠️ ALERT

`review-watcher-misuse`#

input  : all watcher.report(...) calls
output : list of reports that look positive ("success", "completed", "ok", ...)
         → recommendation: remove or rephrase as negative

`review-comment-drift`#

input  : every code comment
output : list of comments that no longer match the adjacent code
         (typical: comment mentions foo, code mentions bar)

Helps remove stale comments.
“Teach the pattern, not the symptom.”

10.01 — Workflow summary matrix

Wed, 20 May 2026 00:00:00 +0000

10.01 — Workflow summary matrix#

Synthetic overview of every ecosystem workflow.

Recap#

Repo	Workflow	Trigger	OS	Stack	Effect	Detail
`ocarina`	`main_ci.yml`	push/PR main, dispatch	ubuntu + windows × py 3.14 (option 3.15-dev)	venv cache, make install-on-ci	make check-coding-style + make test + Allure history + Pages deploy	`02-ocarina-workflows.md`
`ocarina`	`dev_ci.yml`	push dev/feature/fix, PR dev, dispatch	ubuntu × py 3.14	venv cache	check-coding-style + test + coverage summary (non-gating)	`02-ocarina-workflows.md`
`ocarina`	`unstable_python_full_build.yml`	cron (monthly), dispatch	ubuntu + windows × py 3.15-dev	`PIP_ONLY_BINARY=":all:"`	full build on pre-release Python	`02-ocarina-workflows.md`
`ocarina-example`	`main_ci.yml`	push/PR main, dispatch	ubuntu + windows × py 3.14	venv cache	check-coding-style	`03-example-workflows.md`
`ocarina-example`	`dev_ci.yml`	push dev, dispatch	ubuntu × py 3.14	venv cache	check-coding-style	`03-example-workflows.md`
`ocarina-example`	`e2e.yml`	dispatch (env `OC`)	ubuntu + service `redis:8.x` + Firefox + geckodriver 0.35.0	venv cache	full run, upload traces	`03-example-workflows.md`
`ocarina-with-ai-example`	`ai_proof_ci.yml`	push main, PR, dispatch	ubuntu × py 3.14	venv cache	ruff format check + ruff check + mypy	`04-ai-workflows.md`
`ocarina-with-ai-example`	`ai_proof_e2e.yml`	dispatch	ubuntu × firefox+chrome matrix	venv cache, geckodriver 0.36.0 / auto-matched chromedriver	Heroku dyno warm-up, run, sed-filter ChromeDriver stacktraces, upload	`04-ai-workflows.md`
`igoristan`	`ci-pr.yml`	PR `**`, dispatch	ubuntu × node 24 + pnpm 11	wireit	format check + lint + typecheck (parallelized)	`05-igoristan-workflows.md`
`igoristan`	`deploy.yml`	push main, dispatch	ubuntu × node 24 + pnpm 11	concurrency group `pages`	`pnpm install --frozen-lockfile` + `pnpm build` + upload Pages	`05-igoristan-workflows.md`
`ocarina-holy-book`	`deploy.yml`	push main, PR, dispatch	ubuntu × node 24 + pnpm 11	`TZ=Europe/Paris`, concurrency group `pages`	`pnpm install` + `pnpm build` + upload Pages	`06-holy-book-workflow.md`
`tests-workers`	none	—	—	Vercel	`vercel deploy`	`07-tests-workers-vercel.md`

Composite action#

Action	Location	Use
`allure-history`	`ocarina/.github/actions/allure-history/action.yml`	Composite: Bun + Allure 3.9.0 + restore/save `history.jsonl` on a dedicated branch

Patterns#

PR workflows (light, auto)#

ocarina/main_ci.yml                                       # python 3.14
ocarina/dev_ci.yml
ocarina-example/main_ci.yml
ocarina-example/dev_ci.yml
ocarina-with-ai-example/ai_proof_ci.yml
igoristan/ci-pr.yml

All run fast.

11.01 — Sovereign grammar

Wed, 20 May 2026 00:00:00 +0000

11.01 — Sovereign grammar#

No imposed DSL. No plugin ecosystem. Extension by composition, never by inheritance.

Vision#

Holy Book quote (chapter “What is Ocarina?”):

What if delegating one’s grammar to “standards” had never been a good idea?

The real gap in E2E testing is not about imposing the “best” Newspeak.
Short answer: Ocarina is extensible.

Any verb and conjunction can be created, all governed by strict rules that keep the whole thing deeply consistent.

12.01 — Every manifesto quote, sourced

Wed, 20 May 2026 00:00:00 +0000

12.01 — Every manifesto quote, sourced#

The Holy Book is packed with quotes whose origin is never announced in the text. They are passwords: if you recognize them, you know where the author comes from; otherwise, you read the slogan without the subtext.

Listing#

#	Quote (Holy Book)	Author / Source	Year
1	“In the Lulzboat, salute, bitch, and show some respect.”	YTCracker — `#antisec` (single, official theme song of Operation AntiSec). Spotify track, YTCracker Wikipedia page	June 22, 2011
2	“THE FUCK YOU THINK THIS IS? You HOLLOW! YOU HOLLOW, YOU UNDERSTAND ME? YOU’RE WORTHLESS, YOU’RE FUCKING TRASH!”, signed “(btw: RIP, DG descendant…)”, then continued in French: “ON VA TE REMPLACER ET TU RETOURNERAS HARCELER TES PAIRS SUR DOTA ET TE BRANLER SUR DES MACROS VBA COMME UNE MERDE! […] YOU FUCKED WITH US!”	Yung Innanet (kayos) — lyrics from `true colors`, SoundCloud — queed-inc/true-colors. Original sysadmin of VX Underground, GitHub profile. Passed away on October 18, 2025. The DG descendant refers to Digital Gangster, YTCracker’s forum. See `06-yung-innanet-vxug.md`	—
3	“Of currency minted from factoring digits” (in French in the Holy Book: “ces monnaies forgées de la factorisation des nombres”)	YTCracker — `Cryptoilluminati` (album A Side Quest for Fractional Cents). SoundCloud. Exact line: “Told you to snap up a modest position / Of currency minted from factoring digits / Which of you listened?”	2022
4	“We Can Do All What You Can’t Do.”	Indonesian collective YogyaCarderLink (YCL) mantra, one of the earliest carding / defacement groups based in Yogyakarta. See `05-indonesian-hackers.md`	early 2000s
5	“I’m the bug you can’t kill." — Holy Book: “Je suis le bug dont tu ne pourras jamais te débarrasser.”	Not reliably attributable. Idiom of the 2000s hacker scene, in the lineage of “I’m the null at the end of the string” (YTCracker, Nerdlife, 2006). See `03-ytcracker-nerdcore-digital-gangster.md`	—
6	“HACK THE PLANET”	Iconic slogan of the 1990s hacker scene. Popular origin: the film *Hackers* (1995, Iain Softley), war cry of the character Cereal Killer. Picked up by the real scene (mailing lists, defaces, conferences).	1995 (spread)
7	“YOU FUCKED WITH US!” / “Don’t fuck with us.”	Direct callback to the `Don't fuck with us` mantra, recurring signature of YogyaCarderLink deface pages and more broadly of the 2000s carding/defacement scene. The shift from future/present ("don’t”, warning) to past ("you fucked", finding) is the rhetorical pivot: we warned you, you did it anyway. See `05-indonesian-hackers.md` and `02-lulzsec-lulzboat-antisec.md`	2000s
8	“Fucking skids. Fucking normies!”	Native IRC terms: `skid` = abbreviation of script kiddie; `normie` = average / uninitiated user. Not a single attributable quote — it’s EFnet / 2600 / Digital Gangster speech. See `04-zoneh-irc-efnet.md`	—
9	“from Zone-H to a settled life”	Zone-H = public deface archive, founded on March 2, 2002 by Roberto Preatoni (Sys64738). See `04-zoneh-irc-efnet.md`	2002
10	“CODE IS LAW”	Lawrence Lessig, Code and Other Laws of Cyberspace, MIT 1999. Warning cry on regulation by code. Repurposed as ideal by crypto / Ethereum from 2015 onward.	1999 / 2015
11	“Also read: Haters, by Paul Graham.”	Essay by Paul Graham (Y Combinator co-founder), `paulgraham.com/fh.html`. On hostile online comments.	—
12	“I won’t let you pay me for my open source — Fuck You”	David Heinemeier Hansson (DHH), Ruby on Rails creator. Blog post Hey.	—
13	“Retry flaky blocks.”	Yegor Bugayenko, Prompt (`github.com/yegor256/prompt`). Author of Angry Tests.	—
14	“An idiot admires complexity, a genius admires simplicity…”	Terry Davis (1969–2018), TempleOS creator. Considered by some “the smartest programmer who ever lived”. Programmer affected by schizophrenia and one of the most iconic victims of cyber-harassment.	—
15	“To gain knowledge, add things every day. To gain wisdom, remove things every day.”	Lao-Tzu, Tao Te Ching. Alternative for those who don’t dare quote Terry A. Davis due to controversy.	6th century B.C.
16	“Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.”	Antoine de Saint-Exupéry, Wind, Sand and Stars (1939).	1939
17	“Style, for both writer and painter, is a matter not of technique but of vision.”	Marcel Proust (interview).	—
18	“For now, live the questions…”	Rainer Maria Rilke, Letters to a Young Poet (1903-1908).	1903-1908
19	“Muddy water is best cleared by leaving it alone.”	Attributed to Alan Watts.	—
20	“Peace out.” → YTCracker — Robots Will Definitely Take Your Job	YTCracker, SoundCloud. The title is the thesis: AI will replace incompetent coders. The expression “Peace out” is regularly used in this community as a casual / cold farewell.	—

Hacker scene axis (1, 7, 9, 11) → 02-lulzsec-lulzboat-antisec.md, 04-zoneh-irc-efnet.md
YTCracker / Nerdcore axis (1, 3, 5, 20) → 03-ytcracker-nerdcore-digital-gangster.md
Indonesian axis (4) → 05-indonesian-hackers.md
Yung Innanet axis (2) → 06-yung-innanet-vxug.md
Philosophical / wisdom axis (14, 15, 16, 17, 18, 19) → already covered in ../01-philosophy/04-citations-and-influences.md
Politics of code axis (10, 11, 12, 13) → already covered in ../01-philosophy/05-political-stance.md

Why sources matter#

The Holy Book never cites its sources. Not by negligence, by scene convention: if you recognize, you belong; if you don’t, you read the surface text, which also works. It’s a literary device as old as underground communities. LulzSec did it on their pastebins.

99.01 — Glossary

Wed, 20 May 2026 00:00:00 +0000

99.01 — Glossary#

Terminology used in the Ocarina ecosystem. Original sources in parentheses.

Railway Oriented Programming (ROP)#

Term	Definition
ROP (Wlaschin, F#)	Functional pattern: success and failure are two parallel rails; a failure switches the computation to the failure rail, where it stays (short-circuit).
`Result[T]`	Discriminated union `Ok[T] \| Fail`. Error carried as value, not raised exception.
`Ok[T]`	Success wrapper, `value: T`.
`Fail`	Failure wrapper, `error: Exception`.
`is_ok`, `is_fail`	`TypeGuard`s that narrow a `Result[T]` to `Ok[T]` or `Fail`.
`Action[T]`	`Thunk[Result[T]]` — argumentless function returning a `Result[T]`.
`ActionStart[T]`	Initial state of the ROP action builder. Expects `.failure(...)`.
`ActionFailure[T]`	After `.failure(...)`. Expects `.success(...)`.
`ActionSuccess[T]`	After `.success(...)`. Expects `.execute()`.
`ActionChain[T]`	After `.execute()`. Carries `has_failed: bool` and `result: Result[T]`. Allows `.then(...)`.
`NeutralActionStart[T]`, `NeutralActionFailure[T]`, `NeutralActionSuccess[T]`	Inert states of the failure rail. Stub by no longer doing anything.
`ChainRunner[T]`	Lazy encapsulation of an `ActionChain`. Executed by `.run()`.
`drive_page`	Opinionated semantic alias for `chain_actions`. “Take control of a page”.
`match_page` / `when`	Conditional branching. First-match wins.
`create_act`	Low-level primitive to create `act` (test step). Wrapped by the user project.
`act` (project-side)	User wrapper for `create_act` with a project-specific `on_failure` hook. Represents a test step.

ISTQB / test-professional vocabulary#

Term	Definition
ISTQB	International Software Testing Qualifications Board. Professional body of software testing.
Test cycle	Top level. A complete execution.
Test campaign	Level under the cycle. Not directly defined in ISTQB but recognized in tester vocabulary.
Test suite	Level under the campaign. A collection of executable tests.
Test case	A test case. Atomic unit.
Test step	A test step. Atomic action inside a test case.
Smoke test	Minimal check proving the system is running. If failure, the rest is useless.
Setup / Teardown	Pre/post-condition of a test.

Ocarina (orchestration)#

Term	Definition
`Test[Driver]`	ISTQB test. Metadata + scenario factory + fragments + skip.
`TestSuite[Driver]`	ISTQB suite. Parallelization (thread pool), saturation, ID filtering, retries.
`TestCampaign[Driver]`	Campaign. Sequence of suites with shared workers config.
`TestCycle[Driver]`	ISTQB cycle. Smoke (with `fail-fast` vs `wait-for-all` modes) + main.
`TestExecutor[Driver]`	Executes a single attempt of a test. Stateless.
`TestFlow[Driver]`	Replay loop (1 + max_retries) with linear backoff.
`TestRunner[Driver]`	Output of `Test.spawn(driver, logger)`. Aggregator of chain_runners + setup + teardown + watchers.
`Scenario[Driver]` (frozen dataclass)	Encapsulates `test_chain`, `setup`, `teardown`, `watchers`.
`TestChain`	`Sequence[ChainRunner[Any]]`. The sequence to execute to apply the test.
`Watcher[Driver]`	Daemon thread observing something extra on a test. Periodic callback.
`Saturation`	Random test-cloning mechanism to reach `max_workers`. Copies named `[COPY N] <name>` (or `[+N]` per convention).
`Transient errors`	Tuple of exceptions triggering a replay.
`max_retries_per_test`	Number of replays. Default, 8 ("9 lives like a cat 🐱").
`autoscreen_on_fail`	Automatic screenshot on failing test step.

Ocarina (invariants DSL)#

Term	Definition
`validate(value, name="...")`	Entry point of the invariants DSL.
`ValidationStartBlock[T]`	Initial state. Expects `.assert_that(...)`.
`ValidationAssertBlock[T]`	After `.assert_that(...)`. Accepts `.assert_that`, `.otherwise`, `.then`, `.execute`.
`.assert_that(predicate)`	Adds a logical AND.
`.otherwise(predicate)`	Adds a logical OR. Combined via `_any_of`.
`.then(new_value)`	Switches the current value in the chain. Keeps accumulated errors.
`.execute()`	Executes the chain, returns a `_ValidationResult` (inert until `.raise_if_invalid()` is called).
*`chain_validations()`**	Merge several `ValidationAssertBlock`s into one.
`InvariantViolationError`	Exception raised by predicates.
`AggregateInvariantViolationError`	Aggregation of multiple `InvariantViolationError`s. Raised by `.raise_if_invalid()`.
`DuplicatesError`	`InvariantViolationError` subclass raised by `has_unique_elements`.
`BusinessInvariantValidator.create`	Factory for business invariants.
`FrameworkInvariantValidator.create`	Factory for framework invariants.

Ocarina (infra + ports)#

Term	Definition
`POMBase`	Framework-agnostic ABC. Methods `verify` + `get_current_title`.
`SeleniumTitleMixin`	Selenium-specific mixin. Implements `get_current_title` and types `_driver: WebDriver`.
`WebDriversPool[Driver]`	Thread-safe drivers pool. Semaphore + Queue (THE QUEUE damn it!) + warmup with watchdog.
`WarmupTimeoutError`	Raised by `pool.warmup()` when it stalls.
`DriverBuilder[Driver]`	Builder that manages the profile tmp dir and produces `(driver, dispose)`.
`BuiltWebDriver[Driver]`	`tuple[Driver, Effect]` — driver + dispose.
`Screenshotter[TDriver]`	Thread-safe screenshot utility. Burst mode, healthcheck.
`ScreenshotterConfig[TDriver]`	Config (frozen dataclass): output_dir, file_ext, health_check, save_full_page, etc.
`ActCounter`	Interface. Counts `act`s called per attempt.
`ThreadsBasedActCounter`	Thread-local implementation of `ActCounter`.
`ILogger`	Logging port (ABC). Methods: `debug`, `info`, `warning`, `error`, `critical`, `success`, `test_name`, `exception`, `raw`, `set_prefix`, `set_domain_taxonomy`, `cleanup`.
`ITakeScreenshot[Driver]`	Protocol `(driver, logger, category) -> None`.
`PrintLogger` / `FileLogger` / `PrintAndFileLogger` / `MutedLogger`	4 canonical implementations of `ILogger`.
`driver_healthcheck(driver)`	Pings `driver.title`; raises `DriverDiedError` if THE DRIVER IS DEAD.
`DriverDiedError`	Exception raised by `driver_healthcheck`.
`PageVerificationError`	Exception raised by `POM.verify` when the page isn’t the right one.
`NoMatchingBranchError`	Exception raised by `match_page` when no `when` matches.

Ocarina (opinionated)#

Term	Definition
`CliBuilder`	Declarative builder over argparse. Error aggregation.
`CliArg`	Declaration of a CLI argument.
`CliStore[TKeys]`	Write-once store for parsed CLI values. `TKeys: Literal[...]` for autocomplete.
`_CliField[T]`	Write-once field with validator.
`phantom_validate`	No-op validator for fields that don’t need extra validation.
`CliStoreSingleton`	Singleton around `CliStore`.
`create_selenium_auto_cli_store()`	Factory that dispatches by OS.
`bootstrap(test_cycle, run_plugins, post_exec)`	Canonical entry point.
*`run_plugins(plugins, exceptions_logger)`**	Runs plugins in parallel if N>1.
`pretty_print_results`	Plugin that prints results to the terminal (ANSI).
`generate_docx_proof`	Plugin to create DOCX test proofs.
`generate_json_results`	Plugin that transcribes the same results as `pretty_print_results`, in JSON format.
`timing`	Context manager that measures duration.

Functional programming#

Term	Definition
`Effect`	`Callable[[], None]` — argumentless, returnless function, deferred.
`Thunk[T]`	`Callable[[], T]` — argumentless function, deferred.
`Closure`	Function capturing an environment.
`Fold` / `reduce`	Reduction of a sequence to a single value (catamorphism).
`TypeGuard`	PEP 647 — annotation that narrows a type on the type-checker side.
`Discriminated union`	Union of disjoint types, discriminated by a test (typically `isinstance`).
`Sealed union`	Discriminated union whose variants are all `@final`.
`@final`	PEP 591 — declares that a class can’t be subclassed (no infinite covariance).
`Self`	PEP 673 — return type that refers to the instantiated class (not the declared class).
`Protocol`	PEP 544 — structural type; any object with the right shape is usable.
`PEP 695`	Generics syntax `class Foo[T]:` (Python 3.12+).

Author vocabulary#

Term	Meaning
Slipologue	Neologism. The one pretending “to know everything” without practice. Pollutes technical discussions with mental models. A pain in the ass using ChatGPT or Wikipedia to always have an answer for everything, pretending to speak about a subject he masters when he doesn’t.
Vues de l’esprit (mental models)	Imaginary concept; inapplicable theoretical vision.
White box	Auditable, readable code, no hidden logic. Opposite of black box.
Raw data	Source code, files, simple formats.
Programming astrology	Esoteric patterns without measurable benefit.
In the Lulzboat, salute, bitch, and show some respect.	Quote from YTCracker — `#antisec` (2011), official anthem of Operation AntiSec. See `../12-manifesto-deciphered/01-sourced-citations.md`
Fucking skids, fucking normies	IRC / EFnet identity marker.

Hacker scene (chapter 12)#

Term	Definition
AntiSec movement (1999)	Movement opposed to the cybersecurity industry and full disclosure. Refusal to publish exploits / vulnerabilities. Targets: SecurityFocus, Packet Storm, Bugtraq mailing list, etc.
Operation AntiSec (2011)	Resurrection of the movement by LulzSec + Anonymous. 50 days of hacks (May-June 2011).
LulzSec	Hacker group active May-June 2011. Anonymous splinter. Manifesto “we do it for the lulz”. Arrests in 2012.
The Lulzboat	LulzSec’s identity metaphor. Pirate-ship ASCII art signing their communiqués.
Sabu	Hector Monsegur, LulzSec leader, turned by the FBI in June 2011.
Topiary	Jake Davis, LulzSec spokesperson.
YTCracker	Bryce Case Jr. (born 1982). Nerdcore rapper, former black hat (NASA Goddard 1999), founder of Digital Gangster (forum, 2005).
Nerdcore	Hip-hop subgenre whose lyrics are really for nerds (code, hacking, sci-fi, math). Coined by MC Frontalot (2000).
Digital Gangster	Hacker forum founded by YTCracker in 2005 (`digitalgangster.com`). 36,000 members at peak. Source of several iconic hacks (Paris Hilton, Miley Cyrus, Twitter Obama, etc.).
NerdRap Entertainment System	YTCracker’s founding album (2005). Beats over NES OSTs, Nerdcore lyrics.
Darknet Diaries	Podcast by Jack Rhysider on cybersecurity history. *Episode 78 (Nerdcore)* is dedicated to YTCracker. Transcript: https://darknetdiaries.com/transcript/78/
Zone-H	Public website-deface archive (founded March 2, 2002 by Roberto Preatoni / Sys64738, based in Estonia). 2002-2015 grey-hat scoreboard.
IRC	Internet Relay Chat (1988). Multi-user text-chat client/server protocol. Central social medium for hackers 1993-2012.
EFnet	Eris-Free Network. Historical IRC network (1990). Center of the warez, 0day, phreakers scene 1996-2008.
Channel (`#name`)	IRC room.
`skid` / script kiddie	Hacker running scripts they don’t understand. Insult.
`normie`	Average user, uninitiated. Insult.
`lamer`	BBS-era variant of skid.
`gr33tz`	Greetings, crew list, at the bottom of a deface.
`zine`	E-zine, underground magazine, often ASCII.
VX Underground (VXUG)	Public malware-samples repository (founded ~2019 by smelly_vx). Original sysadmin: Yung Innanet / kayos.
Yung Innanet / kayos	Original sysadmin of VX Underground and musician. Passed October 18, 2025. The Holy Book directly quotes lyrics from his track `true colors` (SoundCloud), signed “(btw: RIP, DG descendant…)”.
YogyaCarderLink (YCL)	Indonesian hacker collective (Yogyakarta), early 2000s. Two recurring mantras on their defaces: “We Can Do All What You Can’t Do.” and `Don't fuck with us.`
Honker (红客)	Chinese red hacker. Patriotic, ideologically driven hacker. Appeared after the 1998 Indonesia riots.
Villains but not Monsters	Moral distinction at the heart of the hacker scene: a Villain confronts power, a Monster persecutes the weak. Real enthusiasts hate monsters (often former bullied who reproduce the harm they suffered).
DEF CON	Annual hacker conference, now in Las Vegas (formerly at the Caesars Forum).
BOFH (Bastard Operator From Hell)	Fiction series by Simon Travaglia (New Zealand), published on Usenet in the ’90s then on The Register. Archetype of the user-despising sysadmin. Source of the vocabulary PEBKAC, RTFM, ID-10-T error.
Usenet	Distributed newsgroups system. Founding medium of hacker culture.
Shodan	Search engine for internet-connected devices (IP cameras, ICS, IoT, open servers). Founded by John Matherly. `shodan.io`
ViolVocal	French-speaking community (mid-2000s) of organized prank callers / phone harassers on forum + Mumble/TeamSpeak server. SIP spoofing, public call streams, doxing, impersonating police officers to consult restricted databases without authorization, etc. Shut down after prosecutions. Francophone case of underground cruelty.
4chan / /b/	Imageboard founded by moot (Christopher Poole) in 2003. /b/ = no-rules, no-archive, totally anonymous board. Matrix of Anonymous (2006-2008) and modern meme culture. Community regularly orchestrating harassment, having notably degraded Terry A. Davis’s health.
Anonymous	Collective entity emerged from 4chan /b/ around 2006-2008. Op Chanology (Scientology 2008), Op Tunisia (2011), Op Sony (2011). IRC coordination.
Doxing	Publication of a target’s personal info with intent to harm.
Swatting	False emergency call (often SIP-spoofed) declaring a serious crime at the victim’s address, triggering SWAT deployment. Fatal cases documented.
OSINT	Open Source Intelligence. Information gathering from public sources.
OPSEC	Operations Security. Rigorous maintenance of operational anonymity over time.
Honeypot	Fake server / fake account / fake leak baiting attackers to detect them. Scene defensive tool.
Snitch / Fed	Informant / undercover federal agent. Top-priority detection in any underground community.
Prompt injection	Insertion of malicious content into an LLM’s context to hijack its behavior. OWASP LLM01:2025. First in the LLM Top 10.
MCP (Model Context Protocol)	Anthropic standard protocol (2024) to expose tools and resources to an LLM. Each third-party MCP server adds an attack surface.
Hard-won rules	Internal project conventions documented in `CLAUDE.md` after costly lessons. Prevents LLMs from repeating errors already encountered.

Ocarina ideology#

Term	Definition
Villain (hacker sense)	Reclaimed identity of the sovereign hacker acting outside institutions, opposed to conventions and corporate branding. The Villain confronts power but respects the weakest.
Monster (hacker sense)	One who technically exploits their skill to persecute vulnerable people (harasser, doxxer, etc.). Structural enemy of the real hacker scene.
Tooling culture	Conviction that well-written technical tools (Nmap, Wireshark, Metasploit, Burp, sqlmap, et al.) made by small teams are worth a thousand marketing presentations.
Tribal loyalty (hacker scene)	Absolute intra-community loyalty + extreme external suspicion. Long admission tests, vouching by established members, brutal excommunication on betrayal.
Eyes everywhere	Operational hyper-vigilance learned in the underground context (IRC admin legally responsible for their channels’ actions).

Industry / counter-models#

Term	Definition
Infopreneur	Entrepreneur whose product is sold information: courses, e-books, masterminds. American model (Dan Kennedy, Russell Brunson), imported into France via Tugan Bara.
Copywriting	Art of writing persuasive sales texts. Core trade of infopreneurs. Largely automatable by AI since 2023.
Funnel	Sales funnel: free content → front-end product (€97) → flagship product (€997-4997) → premium coaching.
Marketing Underground	Tugan Bara’s flagship program (2018-2023). Owned “bad guy” posture.
Tugan Bara / Arnaud Labossière	French archetype of the 2018-2024 infopreneur model. HEC dropout. Sold Tugan.ai in 2024. Ultimately the only infopreneur who really explained the profession to a whole francophone-scene community.
MRR	Monthly Recurring Revenue. Monthly amount billed to subscription customers. Central SaaS indicator.
ARR	Annual Recurring Revenue. Annual amount earned from SaaS sales.

AI, ML, RL#

Term	Definition
LLM	Large Language Model. Transformer model pre-trained on a large corpus. Claude, GPT, Gemini, Llama, Mistral.
Transformer	Architecture introduced by Attention Is All You Need.
Foundation model	Pre-trained model reused for multiple tasks via fine-tuning or prompting.
RL (Reinforcement Learning)	Learning by interaction with an environment, guided by a reward signal. Sutton & Barto 1998.
Constitutional AI (CAI)	Anthropic alignment method (Bai et al., 2022). The model critiques and revises its own responses according to a written constitution.
Probe	Empirical learning primitive for AI.
llms.txt, llms-full.txt	Jeremy Howard standard (fast.ai), 2024. Short Markdown index (`llms.txt`) + concatenated full doc (`llms-full.txt`) for agent ingestion.
SKILL.md	Lets an AI agent plug into a project skill.
CLAUDE.md	Provides Claude Code with a set of rules.

00.02 — Stack / responsibility / license matrix

Wed, 20 May 2026 00:00:00 +0000

00.02 — Stack / responsibility / license matrix#

Repository	Role	Language	Version	Primary stack	Tooling stack	Distribution	License
`ocarina`	Browser e2e test framework	Python	3.14+	`hatchling`, `python-docx` (sole runtime dependency), `selenium` + `playwright` (dev only)	`ruff` (ALL), `mypy` strict, `pytest`, `hypothesis`, `pytest-mypy-plugins`, `syrupy`, `prysk` (cram), `allure-pytest`, `pre-commit`, `twine`, `build`	PyPI, v1.1.10	MIT
`ocarina-example`	Canonical e2e suite against the Igoristan	Python	3.14+	`ocarina`, `selenium ≥ 4.40`, `python-dotenv`, `dogpile.cache`, `redis`	`ruff`, `mypy`, `pre-commit`	Source only	MIT
`ocarina-with-ai-example`	e2e suite against CURA Healthcare, co-written with Claude Code	Python	3.14+	`ocarina ≥ 1.0.3`, `selenium ≥ 4.40`	`ruff`, `mypy`, `mypy-extensions`, `typing-extensions`, `pre-commit`	Source only	MIT
`igoristan`	Public SUT, deliberately chaotic web app	TypeScript	6.0.x	React 19.2, Vike 0.4.258 (SSG), Vite 7.3, TailwindCSS 4 (alpha), `valibot`, `react-hook-form`, `react-dropzone`, `usehooks-ts`, `throttleit`, `lucide-react`, `uuid`	`pnpm 11`, Node 24, `wireit` (orchestrator), `eslint 9` (flat), `prettier 3.5`, `husky`, `lint-staged`, `commitlint`, `commitizen`, `terser`, `rollup-plugin-visualizer`, `vite-plugin-compression`, `@qalisa/vike-plugin-sitemap`	GitHub Pages (`/igoristan/`)	none
`tests-workers`	OTP / Corsicadex backend, the substrate that exercises parallelization and API tests	TypeScript	5.9.3	Vercel Edge Functions (`runtime: "edge"`), `@upstash/redis`, `otplib`, `next` types (`NextRequest`)	`pnpm 11.x`, `@vercel/node` (types)	Vercel: `https://tests-workers.vercel.app`	ISC
`ocarina-holy-book`	Public documentation + AI skills + PDFs	TypeScript	6.0.x	VitePress 2 alpha, `@sugarat/theme`, `vue 3.5`, `pagefind`, `vitepress-plugin-image-optimize`	`pnpm 11`, Node 24, `eslint 9`, `prettier 3.8`, `husky`, `lint-staged`, `commitlint`, `sass-embedded`	GitHub Pages (`/ocarina-holy-book/`)	MIT

Python early adopter#

Python 3.12+ feature	Use in Ocarina
PEP 695 (`class Foo[T]:`)	Generic signatures everywhere (`TestSuite[Driver]`, `Watcher[Driver]`, `Test[Driver]`, `Result[T]`, `Ok[T]`, `Thunk[T]`, etc.)
PEP 695 type aliases (`type X = ...`)	Every alias: `type Result[T] = Ok[T] \| Fail`, `type Effect = Callable[[], None]`, `type Thunk[T] = Callable[[], T]`, `type Mode = Literal[...]`
`TypeGuard` (Python 3.10+)	`is_ok`, `is_fail`, `is_test_result_ok`, `is_test_result_fail`, `is_test_result_skipped`
`Self` (3.11+)	Fluent returns from POMs, loggers, invariants
`@final` (3.8+)	Locks critical classes (`Watcher`, `Test`, `TestCycle`, `ChainRunner`, `Ok`, `Fail`, …)
`Unpack` (3.11+)	`HumanizedDriver` signature in `ocarina-example`
`Protocol` (3.8+)	`ScreenshotDriver`, `SupportsWrite[str]`
`Literal` (3.8+)	All enums (`SeleniumCliStoreKeys`, `LOGGERS_CHOICES`, `Mode`)
`Never` (3.11+)	`_SilentArgumentParser.error` signature

Practical consequence: there is a dedicated CI workflow unstable_python_full_build.yml that pushes Python 3.15-dev monthly (cron: "0 3 1 * *"), because Ocarina aims to be ready for the next interpreter as soon as it ships. See ../10-cicd/02-ocarina-workflows.md

01.02 — ISTQB vs pytest / Jest / Mocha

Wed, 20 May 2026 00:00:00 +0000

01.02 — ISTQB vs pytest / Jest / Mocha#

The methodological observation#

Past the technical bet on the technical / non-technical barrier (see 01-flip-the-problem.md), there’s a second bet: the one on trade vocabulary.

The ISTQB and professional testers have spent decades building a precise, battle-tested vocabulary: test cycles, campaigns, test suites, test cases, test steps. A clear hierarchy, built to organize, trace and drive software quality.

Automation tools have largely ignored that legacy.

02.02 — The ocarina module tree

Wed, 20 May 2026 00:00:00 +0000

02.02 — The `ocarina` module tree#

The Python source module ships 134 .py files across four conceptual layers.

src/ocarina/
├── __init__.py                              # empty — no global "facade", everything is imported precisely
├── py.typed                                 # PEP 561: declares the package as "typed"
│
├── railway/                                 # Layer 1 — FP primitives
│   ├── __init__.py
│   └── result.py                            # Ok[T] / Fail / Result[T] / is_ok / is_fail
│
├── custom_types/                            # Layer 2 — types and aliases
│   ├── __init__.py
│   ├── effect.py                            # type Effect = Callable[[], None]
│   ├── thunk.py                             # type Thunk[T] = Callable[[], T]
│   ├── tpom.py                              # TypeVar TPOM bound POMBase
│   ├── supports_write.py                    # Protocol SupportsWrite[T], mirrors a type not exposed by Python stdlib
│   ├── built_web_driver.py                  # type BuiltWebDriver[Driver] = tuple[Driver, Effect]
│   ├── scenario.py                          # Scenario[Driver] (frozen dataclass)
│   ├── test_components.py                   # TestChain / TestSetup / TestTeardown / TestWatchers
│   ├── test_runner.py                       # TestRunner[Driver]
│   ├── oc_test.py                           # TestName / TestScenario / TestScenarioFragment
│   ├── oc_test_layers.py                    # TestResult / TestSuiteResult / TestCampaignResults / TestCycleResults
│   ├── selenium/
│   │   ├── built_web_driver.py              # BuiltSeleniumWebDriver
│   │   ├── oc_test_scenario.py
│   │   ├── supported_browsers.py            # type SupportedSeleniumBrowser = Literal["chrome", "firefox", "edge", "safari"]
│   │   └── web_drivers_pool.py              # type SeleniumWebDriversPool = WebDriversPool[WebDriver]
│   └── playwright/
│       ├── built_web_driver.py              # type BuiltPlaywrightDriver = BuiltWebDriver[PlaywrightDriver]
│       ├── oc_test_scenario.py              # PlaywrightTestScenario / PlaywrightTestScenarioFragment
│       ├── supported_browsers.py            # type SupportedPlaywrightBrowser = Literal["chromium", "firefox", "webkit"]
│       └── web_drivers_pool.py              # type PlaywrightDriversPool = WebDriversPool[PlaywrightDriver]
│
├── custom_errors/                           # Layer 2: errors
│   ├── __init__.py
│   └── test_framework/
│       ├── __init__.py
│       ├── no_matching_branch.py            # NoMatchingBranchError
│       ├── pages.py                         # PageVerificationError
│       ├── driver_died.py                   # DriverDiedError
│       └── campaigns.py
│
├── custom_invariants/                       # Layer 2: ready-to-use invariants
│   ├── __init__.py
│   └── testing/
│       ├── __init__.py
│       ├── workers.py                       # validate_workers_amount
│       ├── oc_test_runners_ids.py           # validate_test_runners_ids
│       ├── oc_test_runners_names.py         # validate_test_runners_names (unique + valid filename)
│       ├── oc_test_suites_names.py
│       ├── oc_test_campaigns_names.py
│       └── oc_test_cycles_names.py
│
├── ports/                                   # Layer 3: ports (interfaces)
│   ├── __init__.py
│   ├── ilogger.py                           # ILogger (ABC)
│   └── itake_screenshot.py                  # ITakeScreenshot[Driver] (Protocol)
│
├── pom/                                     # Layer 3: Page Object Model
│   ├── __init__.py
│   ├── base.py                              # POMBase (ABC: verify + get_current_title)
│   ├── selenium/
│   │   ├── __init__.py
│   │   └── muted.py                         # MutedPOM utility
│   └── playwright/
│       ├── __init__.py
│       └── muted.py                         # MutedPlaywrightPOM utility
│
├── aggregates/                              # Layer 3: result aggregates
│   ├── __init__.py
│   └── tests_layers.py                      # is_test_result_ok / _fail / _skipped (TypeGuard)
│
├── dsl/                                     # Layer 4: Ocarina DSL
│   ├── __init__.py
│   ├── invariants/
│   │   ├── __init__.py
│   │   ├── validate.py                      # entry-point validate(), BusinessInvariantValidator, FrameworkInvariantValidator
│   │   ├── assertions.py                    # is_str / is_email / is_positive / is_in / has_unique_elements / each / ...
│   │   ├── errors.py                        # InvariantViolationError / DuplicatesError / AggregateInvariantViolationError
│   │   └── internals/
│   │       ├── __init__.py
│   │       └── validation_chain.py          # ValidationStartBlock / ValidationAssertBlock / _ValidationChain / _any_of / chain_validations
│   ├── testing/
│   │   ├── __init__.py
│   │   ├── oc_test.py                       # class Test[Driver]
│   │   ├── oc_test_suite.py                 # class TestSuite[Driver]
│   │   ├── oc_test_campaign.py              # class TestCampaign[Driver] + campaign_has_failed
│   │   ├── oc_test_cycle.py                 # class TestCycle[Driver] + type Mode + has_test_cycle_failed
│   │   ├── filter_tests_by_ids.py
│   │   ├── watcher.py                       # class Watcher[Driver]
│   │   ├── internals/
│   │   │   ├── __init__.py
│   │   │   ├── test_executor.py             # class TestExecutor[Driver] + ExecutionOutcome (frozen, slots)
│   │   │   └── test_flow.py                 # class TestFlow[Driver]
│   │   ├── selenium/
│   │   │   ├── __init__.py
│   │   │   ├── create_test.py               # create_selenium_test(...)
│   │   │   └── create_watcher.py            # create_selenium_watcher(...) + type SeleniumWatcher
│   │   └── playwright/
│   │       ├── __init__.py
│   │       ├── create_test.py               # create_playwright_test(...)
│   │       └── create_watcher.py            # create_playwright_watcher(...) + type PlaywrightWatcher
│   └── testing_with_railway/
│       ├── __init__.py
│       ├── chain_actions.py                 # class ChainRunner[T] + chain_actions
│       ├── match_page.py                    # When + _match_page_builder + create_match_page
│       ├── constructors/
│       │   ├── __init__.py
│       │   └── create_act.py                # low-level primitive (to be wrapped on the project side)
│       └── internals/
│           ├── __init__.py
│           └── action_chain.py              # ActionStart → ActionFailure → ActionSuccess → ActionChain
│                                            # + Neutral{Start,Failure,Success}  (failure rail)
│
├── infra/                                   # Layer 5: infrastructure
│   ├── __init__.py
│   ├── drivers_pool.py                      # class WebDriversPool[Driver] + WarmupTimeoutError
│   ├── driver_builder.py                    # class DriverBuilder[Driver]
│   ├── screenshotter.py                     # class Screenshotter[TDriver] + ScreenshotterConfig
│   ├── act_counter.py                       # class ActCounter (interface)
│   ├── selenium/
│   │   ├── __init__.py
│   │   ├── create_driver.py                 # _build_firefox / _build_chrome / _build_edge / _build_safari
│   │   ├── create_drivers_pool.py           # create_selenium_drivers_pool
│   │   ├── create_screenshotter.py          # create_selenium_screenshotter
│   │   ├── driver_healthcheck.py            # driver_healthcheck (pings driver.title)
│   │   └── mixins.py                        # SeleniumTitleMixin (typing keyway)
│   └── playwright/
│       ├── __init__.py
│       ├── create_driver.py                 # create_playwright_driver (chromium / firefox / webkit)
│       ├── create_drivers_pool.py           # create_playwright_drivers_pool
│       ├── create_screenshotter.py          # create_playwright_screenshotter + _playwright_save_full_page
│       ├── driver.py                        # class PlaywrightDriver (sync wrapper)
│       ├── driver_healthcheck.py            # playwright_driver_healthcheck (pings driver.title)
│       └── mixins.py                        # PlaywrightTitleMixin (typing keyway)
│
└── opinionated/                             # Layer 6: opt-in, everything that is "nice but replaceable"
    ├── __init__.py
    ├── consts/loggers_choices.py            # LOGGERS_CHOICES = ("terminal", "file", "terminal+file", "muted")
    ├── infra/
    │   ├── __init__.py
    │   └── act_counter.py                   # ThreadsBasedActCounter (thread-local counter)
    ├── cli/
    │   ├── __init__.py
    │   ├── builder.py                       # CliBuilder + CliArg + _SilentArgumentParser
    │   ├── store.py                         # CliStore[TKeys] + _CliField[T] + field(...)
    │   ├── phantoms.py                      # phantom_validate (no-op predicate)
    │   ├── selenium/
    │   │   ├── __init__.py
    │   │   ├── cli_store_singleton.py       # SeleniumCliStoreSingleton (push / get)
    │   │   └── create_cli_store.py          # create_selenium_{auto,win,macos,linux}_cli_store
    │   └── playwright/
    │       ├── __init__.py
    │       ├── cli_store_singleton.py       # PlaywrightCliStoreSingleton (push / get)
    │       └── create_cli_store.py          # create_playwright_{,auto_}cli_store
    ├── dsl/
    │   ├── __init__.py
    │   └── drive_page.py                    # drive_page = chain_actions, a semantic alias
    ├── launcher/
    │   ├── __init__.py
    │   └── bootstrap.py                     # bootstrap(...) + run_plugins(*plugins, exceptions_logger)
    ├── loggers/
    │   ├── __init__.py
    │   ├── create_matching_logger.py        # create_matching_logger("terminal"|"file"|...) + get_default_log_dir
    │   ├── print_logger.py                  # PrintLogger (ANSI)
    │   ├── file_logger.py                   # FileLogger (taxonomy -> file tree)
    │   ├── print_and_file_logger.py
    │   ├── muted_logger.py
    │   ├── custom_types/supported_loggers.py
    │   └── utils/
    │       ├── __init__.py
    │       └── format_metadata_str.py       # format_utc_date_metadata_str / format_current_thread_metadata_str / concat_metadata
    └── plugins/
        ├── __init__.py
        └── reports/
            ├── __init__.py
            ├── pretty_print_results.py      # hierarchical ANSI report
            ├── results_to_json.py           # JSON generator
            ├── docx_tests_proofs.py         # DOCX generator (consumes the log tree)
            └── timing.py                    # context manager `with timing(prefix="Duration:")`

Layered diagram#

┌──────────────────────────────────────────────────────────────────────────┐
│ USER PROJECT (e.g. ocarina-example, ocarina-with-ai-example)             │
│  ┌────────────────────┐  ┌────────────────────┐  ┌─────────────────────┐ │
│  │ pages/ (POMBase)   │  │ scenarios/ (Test)  │  │ adapters/ (act, ...)│ │
│  └────────────────────┘  └────────────────────┘  └─────────────────────┘ │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │ imports
┌─────────────────────────────────▼────────────────────────────────────────┐
│ LAYER 6 — opinionated/  (CLI, loggers, plugins, bootstrap)               │
│   Opt-in. Can be replaced wholesale.                                     │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼────────────────────────────────────────┐
│ LAYER 5 — infra/  (pool, builder, screenshotter, Selenium adapters)      │
│   I/O. No DSL logic.                                                     │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼────────────────────────────────────────┐
│ LAYER 4 — dsl/  (testing, invariants, testing_with_railway)              │
│   Pure DSL, no I/O. All the grammar.                                     │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼────────────────────────────────────────┐
│ LAYER 3 — ports/  +  pom/  +  aggregates/                                │
│   Interfaces and abstractions.                                           │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼────────────────────────────────────────┐
│ LAYER 2 — custom_types/  +  custom_errors/  +  custom_invariants/        │
│   Shapes, aliases, types, exceptions, ready-to-use invariants.           │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼────────────────────────────────────────┐
│ LAYER 1 — railway/  (Result, Ok, Fail, is_ok, is_fail)                   │
│   The functional primitive. No dependencies.                             │
└──────────────────────────────────────────────────────────────────────────┘

This strict stratification rules out import cycles and lets you swap any upper layer without touching the ones below:

02.03.02 — The builder state machine

Wed, 20 May 2026 00:00:00 +0000

02.03.02 — The builder state machine#

Source file: src/ocarina/dsl/testing_with_railway/internals/action_chain.py

Here’s where the entire ROP mechanic lives: four successive typed states that literally (as in: the type-checker literally) refuse any syntactic improvisation. The DSL doubles as its own immune system.

Overview#

                      ┌─────────────────┐
   start(action)  →   │  ActionStart[T] │     an Action[T] = Thunk[Result[T]]
                      └────────┬────────┘
                               │ .failure(failure_handler)
                               ▼
                      ┌─────────────────┐
                      │ ActionFailure[T]│
                      └────────┬────────┘
                               │ .success(success_handler)
                               ▼
                      ┌─────────────────┐
                      │ ActionSuccess[T]│
                      └────────┬────────┘
                               │ .execute()   ── runs action(), fires the handler
                               ▼
                      ┌─────────────────┐
                      │ ActionChain[T]  │     holds (has_failed, result)
                      └──────┬──────────┘
                             │ .then(next_action_or_start)
              ┌──────────────┴──────────────┐
              │                             │
   has_failed=True                   has_failed=False
              │                             │
              ▼                             ▼
   ┌──────────────────┐         ┌───────────────────┐
   │ NeutralAction-   │         │ ActionStart[T]    │  → cycle starts over
   │ Start[T]         │         │  (the next action │
   │ (failure rail:   │         │   will execute)   │
   │  the whole chain │         └───────────────────┘
   │  becomes no-op,  │
   │  while keeping   │
   │  the fluent API) │
   └──────────────────┘
              │
              ▼ (.failure → .success → .execute, all no-op)
   ┌──────────────────┐
   │  ActionChain[T]  │   has_failed=True, result=<accumulated Fail>
   └──────────────────┘

The types `Action`, `FailureHandler`, `SuccHandler`#

type Action[T]        = Thunk[Result[T]]      # () -> Result[T]
type FailureHandler   = Callable[[Exception], None]
type SuccHandler      = Effect                # () -> None

Action[T] is a Thunk. Calling ActionStart(action) does not run anything. The action just gets captured.
FailureHandler gets the exception, not the Fail or the Result. Deliberate: 99% of handlers want to log the exception, take a screenshot, and move on.
SuccHandler is an Effect (no argument). Same idea — a success handler logs a static message, snaps a screenshot, doesn’t need the result.

Typestate Pattern: why you can’t get it wrong#

The chain is strictly linear. Each method returns a different type that only exposes the next legal step:

02.04.02 — Catalog of builtin assertions

Wed, 20 May 2026 00:00:00 +0000

02.04.02 — Catalog of builtin assertions#

Source file: src/ocarina/dsl/invariants/assertions.py — ~25 predicates.

Every assertion follows the same contract:

A direct predicate (value: T) -> None that raises InvariantViolationError on contract violation.
Or a closure when you need a config argument (is_equal_to(cmp), etc.).
Or, occasionally, a higher-order function (HOF) like each. Lives here pragmatically — a dedicated file for a single case would be overkill.

Full table#

Assertion	Direct / closure / HOF	Domain	Description
`is_str(value)`	direct	`Any`	Raises if `value` is not a `str`
`is_none(value)`	direct	`Any`	Raises if `value is not None`
`is_not_none(value)`	direct	`Any`	Raises if `value is None`
`is_equal_to(cmp)`	closure	`Any`	Returns `(value) -> None` that raises if `value != cmp`
`is_not_equal_to(cmp)`	closure	`Any`	Returns `(value) -> None` that raises if `value == cmp`
`is_less_than(cmp)`	closure	`float`	`value < cmp`
`is_less_than_or_equal_to(cmp)`	closure	`float`	`value <= cmp`
`is_greater_than(cmp)`	closure	`float`	`value > cmp`
`is_greater_than_or_equal_to(cmp)`	closure	`float`	`value >= cmp`
`is_positive(value)`	direct	`float`	`value >= 0`
`is_not_zero(value)`	direct	`float`	`value != 0`
`is_in(elements)`	closure	`Any`	`value in tuple(elements)`
`is_file(value)`	direct	`str \| Path`	`Path(value).is_file()`
`is_dir(value)`	direct	`str \| Path`	`Path(value).is_dir()`
`is_iso_date_string(value)`	direct	`str`	`datetime.fromisoformat(value)`
`is_iso_utc_date_string(value)`	direct	`str`	Checks ISO + `tzinfo == UTC`
`is_email(value)`	direct	`str`	No whitespace, exactly one `@`, non-empty parts, domain contains `.`
`has_unique_elements(*, key=None)`	closure	`Iterable[Any]`	Detects duplicates (raises `DuplicatesError`). Type-strict (`1 ≠ True`), supports unhashables.
`is_empty(value)`	direct	`Sized`	`len(value) == 0`
`is_truthy(value)`	direct	`Any`	`bool(value) is True`
`is_valid_filename(value)`	direct	`str`	Cross-platform: forbidden chars, Windows reserved words, no leading/trailing space or dot, length ≤ 255
`each(predicate)`	HOF	`Iterable[Any]`	Applies `predicate` to each element

A few implementations in detail#

`is_email`#

def is_email(value: str) -> None:
    """Assert that the string is a valid email address (fast check)."""
    if " " in value:
        raise InvariantViolationError(f"'{value}' must not contain whitespace.")
    if value.count("@") != 1:
        raise InvariantViolationError(f"'{value}' must contain exactly one '@' character.")
    local_part, domain_part = value.split("@")
    if not local_part or not domain_part:
        raise InvariantViolationError(f"'{value}' must have non-empty local and domain parts.")
    if "." not in domain_part:
        raise InvariantViolationError(f"Domain part of '{value}' must contain at least one '.'.")

Four bare-minimum checks. No RFC 5322 regex. Deliberate: real email validation happens by sending an email, not by regex.

02.05.02 — TestExecutor[Driver]

Wed, 20 May 2026 00:00:00 +0000

02.05.02 — `TestExecutor[Driver]`#

Source file: src/ocarina/dsl/testing/internals/test_executor.py

One job: run one attempt of a test with one driver. Knows nothing about retries, the driver pool, or suite-level aggregation.

`ExecutionOutcome`#

@final
@dataclass(frozen=True, slots=True)
class ExecutionOutcome:
    result: TestResult
    skipped: bool
    setup_failed: bool
    should_retry: bool
    steps_count: int

Field	Type	Meaning
`result`	`TestResult` = `Result[Any] \| None`	The chain’s result (Ok, Fail), or `None` if skip / setup_failed.
`skipped`	`bool`	True if `test_runner.skipped` (i.e. `Test(skipped=True)`).
`setup_failed`	`bool`	True if the scenario’s `setup()` raised.
`should_retry`	`bool`	True if the retry rule applies (transient_error detected).
`steps_count`	`int`	Number of `act` calls; `-1` if skip or setup_failed.

slots=True: blocks dynamic attribute addition, saves memory. This object rides the hot path — slots earns its keep.
frozen=True: immutable, safe to share across threads.
@final: no inheritance.

Execution order for one attempt#

┌──────────────────────────────────────────────────────────────────────┐
│  test_runner = test.spawn(driver, logger_with_taxonomy)              │
└──────────────────────────────┬───────────────────────────────────────┘
                               │
                               ▼
              ┌─────────────────────────────────┐
              │  test_runner.skipped ?          │── True ─► return Outcome(skipped=True, ...)
              └────────────────┬────────────────┘
                               │ False
                               ▼
              ┌─────────────────────────────────┐
              │  logger.test_name(test.name)    │   (annotation)
              └────────────────┬────────────────┘
                               │
                               ▼
              ┌─────────────────────────────────┐
              │  setup() (if not None)          │── raises ─► teardown() (if not None)
              └────────────────┬────────────────┘            ↓
                               │                  return Outcome(setup_failed=True, should_retry=True, ...)
                               ▼
              ┌─────────────────────────────────┐
              │  watchers.start(driver, logger, │
              │                 take_screenshot)│   (1 daemon thread per watcher)
              └────────────────┬────────────────┘
                               │
                               ▼
              ┌─────────────────────────────────┐
              │  _run_chain(chain_runners, ...) │── returns (result, should_retry)
              └────────────────┬────────────────┘
                               │
                               ▼
              ┌─────────────────────────────────┐
              │  watchers.stop()                │   (always)
              └────────────────┬────────────────┘
                               │
                               ▼
              ┌─────────────────────────────────┐
              │  teardown() (if not None)       │   (ALWAYS, even if chain failed)
              └────────────────┬────────────────┘     (exceptions are logged & swallowed)
                               │
                               ▼
              ┌─────────────────────────────────┐
              │  steps_count = act_counter.get()│
              │  return Outcome(...)            │
              └─────────────────────────────────┘

`execute`#

def execute(
    self, test: Test[Driver], *,
    driver: Driver,
    taxonomy: tuple[str, ...],
    logger_with_taxonomy: ILogger,
    logger_without_taxonomy: ILogger,
    attempt: int, max_attempts: int,
) -> ExecutionOutcome:
    test_runner = test.spawn(driver, logger_with_taxonomy)

    if test_runner.skipped:
        return ExecutionOutcome(result=None, skipped=True, setup_failed=False,
                                should_retry=False, steps_count=-1)

    logger_without_taxonomy.test_name(test.name)

    if test_runner.setup is not None:
        try:
            test_runner.setup()
        except Exception as exc:
            msg = f"{test.name} -- Setup failed (attempt {attempt}/{max_attempts}): {exc}"
            logger_with_taxonomy.warning(msg)
            if test_runner.teardown is not None:
                self._run_teardown(test_runner.teardown, test_name=test.name, logger=logger_with_taxonomy)
            return ExecutionOutcome(result=None, skipped=False, setup_failed=True,
                                    should_retry=True, steps_count=-1)

    watchers: Sequence[Watcher[Driver]] = test_runner.watchers or []
    self._start_watchers(watchers, driver=driver, test_name=test.name, taxonomy=taxonomy)

    result, should_retry = self._run_chain(
        test_runner.chain_runners, test_name=test.name, attempt=attempt,
        driver=driver, logger=logger_without_taxonomy,
        logger_with_taxonomy=logger_with_taxonomy, max_attempts=max_attempts,
    )

    self._stop_watchers(watchers)

    if test_runner.teardown is not None:
        self._run_teardown(test_runner.teardown, test_name=test.name, logger=logger_with_taxonomy)

    steps_count = self._act_counter.get()
    return ExecutionOutcome(result=result, skipped=False, setup_failed=False,
                            should_retry=should_retry, steps_count=steps_count)

Two loggers: why#

logger_with_taxonomy vs logger_without_taxonomy:

02.10.02 — DriverBuilder[Driver]

Wed, 20 May 2026 00:00:00 +0000

02.10.02 — `DriverBuilder[Driver]`#

Source file: src/ocarina/infra/driver_builder.py

Encapsulates profile handling (often a tmp copy of a user directory) and produces the (driver, dispose) pair the pool expects.

Why a builder?#

Building a Selenium driver with a profile requires:

Copy the profile to a temp folder (otherwise Firefox/Chrome locks the original).
Start the driver pointing at the temp folder.
At the end: driver.quit(), then delete the temp folder.

DriverBuilder factors out those three steps:

02.11.02 — CliStore[TKeys] + _CliField[T] + phantom_validate

Wed, 20 May 2026 00:00:00 +0000

02.11.02 — `CliStore[TKeys]` + `_CliField[T]` + `phantom_validate`#

Source files: src/ocarina/opinionated/cli/store.py, src/ocarina/opinionated/cli/phantoms.py

Write-once store for parsed CLI values. Each field validates on write. TKeys: Literal[...] gives key autocomplete.

`_CliField[T]` — write-once field#

class _CliField[T]:
    def __init__(self, *, validate: ValidationChainBuilder[T]) -> None:
        self._value: T | _Unset = _UNSET
        self._validate = validate

    def set(self, value: T) -> None:
        if not isinstance(self._value, _Unset):
            raise RuntimeError("Value already set.")
        self._validate(_validate(value)).execute().raise_if_invalid()
        self._value = value

    def get(self) -> T:
        if isinstance(self._value, _Unset):
            raise RuntimeError("Value not set yet.")
        return self._value

1. `_Unset` sentinel#

class _Unset:
    pass

_UNSET = _Unset()

Why not None? Because None can be a legitimate value (--profile-path isn’t mandatory; its post-parse value can legitimately be None). A dedicated sentinel separates “not set yet” from “set to None”.

03.02 — Closures as the primitive of inversion of control

Wed, 20 May 2026 00:00:00 +0000

03.02 — Closures as the primitive of inversion of control#

No DI container. No injection framework. A closure is Ocarina’s injection primitive.

The idea#

A closure captures values from its enclosing scope. Return a function from another function and the outer parameters are available inside, even after the outer function returns.

def make_handler(logger: ILogger) -> Callable[[str], FailureHandler]:
    def make_failure_handler(msg: str) -> FailureHandler:
        def actual_handler(exc: Exception) -> None:
            logger.error(msg, exc=exc)
        return actual_handler
    return make_failure_handler

Also currying: make_handler(logger)(msg)(exc). Each call captures a new layer of environment.

04.02 — Cram tests (prysk)

Wed, 20 May 2026 00:00:00 +0000

04.02 — Cram tests (`prysk`)#

CLI tests in cram format: a .t file contains shell commands and their expected output. Tool: prysk (modern rewrite of cram).

`.t` file#

Valid args produce a deterministic parsed config

  $ touch driver
  $ "$PYTHON" "$TESTDIR/_demo_cli.py" --browser firefox --driver-path driver --workers 3 --wait-timeout 20 --logger terminal
  browser=firefox
  driver_path=driver
  headless=True
  workers=3
  wait_timeout=20
  logger=terminal
  only=()
  exclude=()

First line: title (comment for the human).
Blank line.
Lines starting with $: shell command run.
Following lines (indent 2): expected output.

Actual output differs → test fails.

05.02 — Igoristan routes

Wed, 20 May 2026 00:00:00 +0000

05.02 — Igoristan routes#

`src/config/routes.ts`#

const __ROOT = "/igoristan/";
const DASHBOARD = "dashboard";

const __ROUTES = {
  DONKEY_SAUSAGE_DETECTOR: "donkey-sausage-eater-detector",
  DASHBOARD_NESTED: `${DASHBOARD}/nested`,
  RANDOM_LOADERS: "random-loaders",
  SACRED_UPLOAD: "sacred-upload",
  RANDOM_ERROR: "random-error",
  CHAOTIC_FORM: "chaotic-form",
  CORSICAMON: "corsicamon",
  MADNESS: "madness",
  DASHBOARD,
  HOME: "",
} as const satisfies Routes;

const ROUTES = createRoutes(__ROUTES, __ROOT);

Route	URL	Role	Deliberate chaos
`HOME`	`/igoristan/`	Home with links to other pages, autoplay audio	—
`RANDOM_LOADERS`	`/igoristan/random-loaders`	Pseudo-random loaders	Loaders that stay visible for a variable time
`SACRED_UPLOAD`	`/igoristan/sacred-upload`	`react-dropzone` upload form	—
`DASHBOARD`	`/igoristan/dashboard`	Login (password `figatellu`), optional MFA OTP	`useAuth` may fail 10% of the time even with the right pwd
`DASHBOARD_NESTED`	`/igoristan/dashboard/nested`	Protected page, requires MFA	—
`CORSICAMON`	`/igoristan/corsicamon`	“Corsican Pokédex”, 3 random picks via API key	1/5 chance of artificially raising `Error('lol')`
`RANDOM_ERROR`	`/igoristan/random-error`	Fake error page	Title matched by `ERROR_PAGE_REGEX` on the test side
`CHAOTIC_FORM`	`/igoristan/chaotic-form`	Unstable form	`.catch-me-if-you-can` elements appear at random
`MADNESS`	`/igoristan/madness`	Alternating stories (Cors, ThisIsBastia)	Renders one OR the other at random
`DONKEY_SAUSAGE_DETECTOR`	`/igoristan/donkey-sausage-eater-detector`	Detector for filthy Sicilian shits	30% random fail (BSOD-style)

Page by page#

const links = [
  { href: ROUTES.RANDOM_LOADERS, label: "Random loaders" },
  { href: ROUTES.SACRED_UPLOAD, label: "Sacred upload" },
  { href: ROUTES.DASHBOARD, label: "Dashboard" },
  { href: ROUTES.CORSICAMON, label: "Corsicamon" },
  { href: ROUTES.RANDOM_ERROR, label: "Random Error" },
  { href: ROUTES.CHAOTIC_FORM, label: "Chaotic form" },
  { href: ROUTES.MADNESS, label: "Madness" },
  { href: ROUTES.DONKEY_SAUSAGE_DETECTOR, label: "Donkey Sausage Detector" },
];

home#

8 links to the other pages + autoplay audio Angelus of Jerusalem (amen 🙏).

06.02 — GET /api/otp

Wed, 20 May 2026 00:00:00 +0000

06.02 — `GET /api/otp`#

Source file: api/otp.ts

Code#

import { generate } from "otplib";
import type { NextRequest } from "next/server";
import redis from "../lib/redis";
import isAuthorized from "../lib/isAuthorized";

export const config = { runtime: "edge" };

const SECRET_QUERY_PARAM_KEY = "secret";
const OTP_SECRET_MIN_LENGTH = 32;
const OTP_SECRET_MAX_LENGTH = 64;
const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
const OTP_TTL = 60 * 5; // 5 minutes
const OTP_HISTORY_TTL = OTP_TTL + 60; // 6 minutes
const MAX_FREE_PAYLOAD_SIZE = 4096;

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, OPTIONS",
  "Access-Control-Allow-Headers": "x-api-key, Content-Type",
} as const;

function generateRandomBase32Secret(length: number = 32): string {
  let secret = "";
  const randomValues = new Uint8Array(length);
  crypto.getRandomValues(randomValues);
  for (let i = 0; i < length; i++) {
    secret += BASE32_ALPHABET[randomValues[i] % 32];
  }
  return secret;
}

function ensureSecretLength(secret: string): string {
  const cleaned = secret.toUpperCase().replace(/\s/g, "");
  if (cleaned.length > OTP_SECRET_MAX_LENGTH) {
    const validLength = Math.floor(OTP_SECRET_MAX_LENGTH / 8) * 8;
    return cleaned.substring(0, validLength);
  }
  if (cleaned.length >= OTP_SECRET_MIN_LENGTH) {
    const validLength = Math.floor(cleaned.length / 8) * 8;
    return cleaned.substring(0, validLength);
  }
  const repetitions = Math.ceil(OTP_SECRET_MIN_LENGTH / cleaned.length);
  const repeated = cleaned.repeat(repetitions);
  const validLength = Math.floor(repeated.length / 8) * 8;
  return repeated.substring(0, Math.max(validLength, OTP_SECRET_MIN_LENGTH));
}

export default async function handler(request: NextRequest) {
  if (request.method === "OPTIONS") {
    return new Response(null, { status: 200, headers: corsHeaders });
  }

  if (!isAuthorized(request)) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { "Content-Type": "application/json", ...corsHeaders },
    });
  }

  const { searchParams } = new URL(request.url);
  const freePayload: Record<string, string> = {};
  let payloadSize = 0;

  searchParams.forEach((value, key) => {
    if (key === SECRET_QUERY_PARAM_KEY) return;
    const entrySize = new TextEncoder().encode(key + value).length;
    if (payloadSize + entrySize > MAX_FREE_PAYLOAD_SIZE) {
      payloadSize += entrySize;
      return;
    }
    freePayload[key] = value;
    payloadSize += entrySize;
  });

  if (payloadSize > MAX_FREE_PAYLOAD_SIZE) {
    return new Response(
      JSON.stringify({
        error: "Bad Request",
        message: `Free payload exceeds maximum size of ${MAX_FREE_PAYLOAD_SIZE} bytes (got ${payloadSize} bytes)`,
      }),
      {
        status: 400,
        headers: { "Content-Type": "application/json", ...corsHeaders },
      },
    );
  }

  const rawSecret =
    searchParams.get(SECRET_QUERY_PARAM_KEY) ?? generateRandomBase32Secret();
  const secret = ensureSecretLength(rawSecret);
  const otpCode = await generate({ secret });
  const now = Date.now();
  const expiresAtMs = now + OTP_TTL * 1000;
  const createdAtTimestampLackingMsPrecision = new Date(
    now - (now % 1000),
  ).toISOString();

  const event = {
    ...freePayload,
    otpCode,
    secret,
    createdAtTimestampLackingMsPrecision,
    expiresAt: new Date(expiresAtMs).toISOString(),
  };

  const key = `otp:${now}:${crypto.randomUUID()}`;
  await redis.set(key, JSON.stringify(event), { ex: OTP_HISTORY_TTL });

  return new Response(JSON.stringify(event), {
    headers: { "Content-Type": "application/json", ...corsHeaders },
  });
}

Flow#

1. Request arrives
   ↓
2. If OPTIONS → 200 + CORS headers (preflight)
   ↓
3. isAuthorized(request)? No → 401
   ↓
4. Parse searchParams; everything except "secret" goes into freePayload
   ↓
5. payloadSize > 4 KB? → 400
   ↓
6. secret = ?secret=<X> (if given) else random Base32 32-chars
   ↓
7. ensureSecretLength: enforces 32..64 chars, multiple of 8
   ↓
8. otpCode = generate({ secret })   ← otplib TOTP RFC 6238
   ↓
9. createdAt = floor(now / 1000) * 1000  ← ms stripped
   ↓
10. event = { ...freePayload, otpCode, secret, createdAt, expiresAt }
    ↓
11. key = `otp:<now>:<uuid>`
    ↓
12. redis.set(key, JSON.stringify(event), { ex: 360 })  ← TTL 6 min
    ↓
13. Response = JSON.stringify(event), 200

CORS headers#

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, OPTIONS",
  "Access-Control-Allow-Headers": "x-api-key, Content-Type",
} as const;

* origin: lets Igoristan (https://mojo-molotov.github.io) call the service.
GET, OPTIONS: the only supported verbs.
x-api-key listed explicitly — otherwise the browser blocks it as a non-simple header.

as const makes the object readonly on the TypeScript side.

07.02 — The 5 adapters

Wed, 20 May 2026 00:00:00 +0000

07.02 — The 5 adapters#

Every Ocarina project starts by writing five adapters on top of the framework.
The ocarina-example project provides them as reference.

Listing#

Adapter	Status	File	Purpose
`act`	required	`lib/ext/ocarina/adapters/agnostic/act.py`	Project-specific `on_failure` hook
`match_page`	optional	`lib/ext/ocarina/adapters/agnostic/match_page.py`	Shared exception policy
`EnvGetters`	optional	`lib/ext/ocarina/adapters/agnostic/env_getters.py`	Typed access to env vars
`TestSuite`	required	`lib/ext/ocarina/adapters/selenium/test_suite.py`	Façade: pins `transient_errors`, `max_retries`, `autoscreen`
`TestCampaign`	required	`lib/ext/ocarina/adapters/selenium/test_campaign.py`	Façade: `max_workers` from CLI

`act`#

# lib/ext/ocarina/adapters/agnostic/act.py
from contextlib import suppress
from ocarina.dsl.testing_with_railway.constructors.create_act import create_act
from ocarina.railway.result import Fail
from lib.custom_errors.http import HttpErrorPageReachedError
from lib.ext.ocarina.regex.error_page import ERROR_PAGE_REGEX


def act(pom: TPOM, action: Callable[[TPOM], TPOM]) -> ActionStart[TPOM]:
    def failure_hook(pom: TPOM, exc: Exception) -> Fail:
        with suppress(Exception):
            title = pom.get_current_title()
            is_http_error_page = title and ERROR_PAGE_REGEX.match(title.strip())
            if is_http_error_page:
                http_error = HttpErrorPageReachedError(f"HTTP error page: {title}")
                http_error.__cause__ = exc
                return Fail(error=http_error)
        return Fail(error=exc)

    return create_act(pom, action, on_failure=failure_hook)

get_current_title(): uses POMBase’s mandatory method (see ../02-ocarina/08-pom-base.md).
ERROR_PAGE_REGEX: detects titles shaped like HTTP error pages (^\d{3}\s.* → 500 Internal Server Error).
HttpErrorPageReachedError: project exception, included in transient_errors.

This adapter is what makes error-page replay automatic.

08.02 — CURA Healthcare (SUT)

Wed, 20 May 2026 00:00:00 +0000

08.02 — CURA Healthcare (SUT)#

Ocarina’s first victim#

Hosting: https://katalon-demo-cura.herokuapp.com/
Source: https://github.com/katalon-studio/katalon-demo-cura (PHP, open source, MIT)
Host: Heroku eco-dyno (sleeps after inactivity)
Credentials: John Doe / ThisIsNotAPassword (public, hardcoded on the login page)

Perimeter#

Page	Function
`/`	Marketing homepage
`/profile.php#login`	Login
`/appointment.php`	Booking form (facility, programs, hospital_readmission, visit_date, comment)
`/confirmation.php`	Booking confirmation
`/history.php`	The user’s booking history
`/profile.php#profile`	Profile page (empty placeholder — gap §G-SPEC-2)

Why target CURA#

Open source — we can read the PHP to understand why a given behavior exists.
Plenty of gaps — rich territory for findings.
Public demo — no authorization needed. Stable (maintained by Katalon).

There’s also a tacit reason: Katalon is a competing test-framework vendor (Katalon Studio). It’s poetic to test their demo app with Ocarina.

09.02 — I18n FR/EN/RU

Wed, 20 May 2026 00:00:00 +0000

09.02 — I18n FR/EN/RU#

Every Holy Book page exists in three versions. EN at the root of docs/, FR under docs/fr/, RU under docs/ru/. VitePress routes automatically.

File structure#

docs/
├── index.md                                                        # EN home
├── what-is-it.md
├── first-feedbacks.md
├── setup.md
├── scenarios-composability.md
├── datasets-smoke-tests-setup-teardown-proxy-api-and-caching.md
├── handling-flakiness.md
├── extensibility.md
├── using-ocarina-with-ai.md
│
├── fr/
│   ├── index.md                                                    # FR home
│   ├── what-is-it.md
│   ├── first-feedbacks.md
│   ├── setup.md
│   ├── scenarios-composability.md
│   ├── datasets-smoke-tests-setup-teardown-proxy-api-and-caching.md
│   ├── handling-flakiness.md
│   ├── extensibility.md
│   └── using-ocarina-with-ai.md
│
├── ru/
│   ├── index.md                                                    # RU home
│   ├── what-is-it.md
│   ├── first-feedbacks.md
│   ├── setup.md
│   ├── scenarios-composability.md
│   ├── datasets-smoke-tests-setup-teardown-proxy-api-and-caching.md
│   ├── handling-flakiness.md
│   ├── extensibility.md
│   └── using-ocarina-with-ai.md
│
├── public/
│   ├── favicon.ico
│   ├── logo.png
│   ├── robots.txt
│   ├── .nojekyll
│   ├── .spa
│   └── assets/
│       └── content/
│           └── ...                                                 # shared EN+FR+RU images
│
└── .vitepress/
    ├── config.mts
    ├── blog-theme.ts
    ├── shims.d.ts
    ├── plugins/
    │   ├── llm.ts
    │   ├── pub.ts
    │   ├── skills.ts
    │   └── webp.ts
    └── theme/
        ├── index.ts
        ├── style.css
        ├── user-theme.css
        ├── components/
        │   ├── Pagination.vue
        │   ├── BlogHomeBanner.vue
        │   └── NotFound.vue
        └── assets/
            └── bg.png

Routing#

Page	URL EN	URL FR	URL RU
Home	`/`	`/fr/`	`/ru/`
Pitch	`/what-is-it`	`/fr/what-is-it`	`/ru/what-is-it`
Rant	`/first-feedbacks`	`/fr/first-feedbacks`	`/ru/first-feedbacks`
Setup	`/setup`	`/fr/setup`	`/ru/setup`
…	…	…	…

VitePress auto-builds the language switcher (top right). Clicking “FR” from /setup takes you to /fr/setup.

09.03.02 — Analyse skills

Wed, 20 May 2026 00:00:00 +0000

09.03.02 — Analyse skills#

Dynamic analyses: use the logs / reports of a recent execution to diagnose a failure. Two root-cause skills sit in front of the family — diagnose-root-cause for a deterministic red, diagnose-flake-root-cause for an intermittent one — and route to the controlled analyse-* experiments.

Listing (potentially non-exhaustive)#

Skill	Target
`diagnose-root-cause`	Structured RCA for a deterministic red: re-derive, the synthetic-to-real ladder, root cause sorted into five buckets
`diagnose-flake-root-cause`	Structured RCA for an intermittent failure (a flake): failure rate, signature, correlation; orchestrates the `analyse-*` experiments
`analyse-flakiness`	Widens the `transient_errors` net; chronic deaths are real flakes
`analyse-fixture-flakiness`	Instruments setup/teardown; surfaces cross-test contaminations
`analyse-watcher-flakiness`	Analyzes watcher reliability (volume, dedup, false positives)
`analyse-screenshot-flakiness`	Groups screenshots by `(test, step, browser)`, detects differences

`diagnose-root-cause`#

input  : a deterministic red (fails every run)
output : structured root-cause analysis:
            - re-derive the failure, don't inherit prior assumptions
            - climb the synthetic-to-real ladder (fake driver → real browser)
            - read the source, confirm with a probe
            - root cause sorted into five buckets
         hands off to diagnose-flake-root-cause if the failure proves intermittent

`diagnose-flake-root-cause`#

input  : an intermittent failure (a flake)
output : distribution-based root-cause analysis:
            - establish a failure rate (the distribution is the evidence)
            - pin the signature, correlate
            - route to the right analyse-* experiment, raise the rate to confirm
            - classify into five flake buckets
         the orchestrator of the analyse-* family

`analyse-flakiness`#

input  : logs of the last N runs
output : list of tests that retry often (by % of retries)
         + recommendation:
            - add an exception to the transient_errors tuple
            - investigate a particular test (the issue might come from the test itself)

`analyse-fixture-flakiness`#

input  : tests with setup/teardown
output : tests whose setup fails often
         + recommendation:
            - verify setup idempotency
            - check teardown is clean (otherwise cross-test contamination)
            - move the seed out of setup into a manual init if too fragile

`analyse-watcher-flakiness`#

input  : watcher.report(...) logs over N runs
output : watchers with abnormal reporting:
            - too many emissions (dedup issue)
            - no emissions (the watcher is useless)
            - false positives (expected element reported as intruder)

`analyse-screenshot-flakiness`#

input  : screenshots from N runs, grouped by (test, step, browser)
output : visual flakiness:
            - tests whose screenshots vary abnormally between runs
            - tests that pass but whose look changes
            - identify whether the variation is semantic (real diff) or cosmetic

Uses heuristics (hash, dimensions, dominant palette). Not a real image diff.

10.02 — ocarina workflows (framework)

Wed, 20 May 2026 00:00:00 +0000

10.02 — `ocarina` workflows (framework)#

Three workflows: main_ci.yml (production), dev_ci.yml (dev/feature/fix branches), unstable_python_full_build.yml (monthly cron on Python 3.15-dev).

`main_ci.yml`#

Trigger#

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:
    inputs:
      python_versions:
        description: "Python versions to test"
        type: choice
        required: false
        default: "Stable only"
        options:
          - "Stable only"
          - "Stable + unstable (uses pre-built wheels)"

workflow_dispatch with a Python-version choice. Lets the user trigger a build with 3.15-dev (pre-built wheels only) without waiting for the monthly cron.

11.02 — Auditability in an afternoon

Wed, 20 May 2026 00:00:00 +0000

11.02 — Auditability “in an afternoon”#

Operational commitment: a human must be able to read the whole framework and understand it in a few hours. No hidden magic.

Commitment#

Holy Book quote (chapter “What is Ocarina?”):

For teams constrained by security policies: the code is small, auditable in an afternoon. Nothing hidden. The only external dependencies live in the post-execution plugins and if one of them doesn’t fit, it can be removed without breaking anything else.

12.02 — LulzSec, the Lulzboat, AntiSec

Wed, 20 May 2026 00:00:00 +0000

12.02 — LulzSec, the Lulzboat, AntiSec#

Three distinct subjects: (1) LulzSec as a group, (2) the Lulzboat as identity metaphor, (3) AntiSec as a movement (two versions: 1999 and 2011). The Holy Book invokes them in one breath; each has its own history.

1. AntiSec (1999) — the original movement#

Origin#

In the late 1990s, the infosec industry professionalized: companies formed around selling firewalls, antiviruses, audits. A norm emerged: full disclosure, publicly releasing vulnerabilities, their PoCs, their exploits, with the argument that it forces vendors to patch quickly.

99.02 — Index of cited files

Wed, 20 May 2026 00:00:00 +0000

99.02 — Index of cited files#

Per repo, the source files explicitly cited in the primer. Direct GitHub URLs.

`mojo-molotov/ocarina` — Framework#

Root#

`src/ocarina/railway/`#

result.py

`src/ocarina/custom_types/`#

`src/ocarina/custom_errors/test_framework/`#

`src/ocarina/custom_invariants/testing/`#

`src/ocarina/dsl/invariants/`#

`src/ocarina/dsl/testing/`#

`src/ocarina/dsl/testing_with_railway/`#

`src/ocarina/aggregates/`#

tests_layers.py

`src/ocarina/infra/`#

`src/ocarina/ports/`#

`src/ocarina/pom/`#

base.py

`src/ocarina/opinionated/`#

Tests#

tests/cram/cli_help.t
tests/cram/cli_happy_path.t
(other .ts)
tests/scenarios/conftest.py
tests/scenarios/test_railway_and_action_chain.py
(other test_*.py)
tests/dsl/invariants/test_types.yml
tests/dsl/testing_with_railway/test_types.yml

Workflows#

`mojo-molotov/ocarina-example`#

Code#

Workflows#

`mojo-molotov/ocarina-with-ai-example`#

Docs#

Code#

Workflows#

`mojo-molotov/igoristan`#

Code#

Workflows#

`mojo-molotov/tests-workers`#

Code#

(No GitHub Actions workflow.)

00.03 — End-to-end execution flow of an e2e campaign

Wed, 20 May 2026 00:00:00 +0000

00.03 — End-to-end execution flow of an e2e campaign#

Run python -u src/main.py … on either suite (ocarina-example or ocarina-with-ai-example) and this chain kicks off:

USER  ────────────────────────────────────────────────────────────────────
       python -u src/main.py --browser firefox --workers 3 [...]
              │
              ▼
       (1) parse CLI
           CliStoreSingleton.push(create_selenium_auto_cli_store())
              │
              ▼
       (2) build pool
           create_selenium_drivers_pool(max_size=N)
              │
              ▼
       (3) warm up external dependencies
           - Redis (ocarina-example)
           - Heroku dyno (ai-example, via curl --retry 6)
              │
              ▼
       (4) bootstrap(
              test_cycle  = create_e2e_test_cycle(drivers_pool),
              run_plugins = lambda results: run_plugins(
                                generate_docx_proof, generate_json_results,
                                exceptions_logger=...),
              post_exec   = pretty_print_results + sys.exit(1) on fail
           )
              │
OCARINA  ─────┼──────────────────────────────────────────────────────────
              │
              ▼
       (5) TestCycle.run_all (saturate_workers=True)
              ├─ smoke_tests_campaigns      [mode: fail-fast | wait-for-all]
              │     └─ TestCampaign.run_all
              │           └─ TestSuite.run (max_workers, saturate_workers)
              │                 └─ ThreadPoolExecutor → TestFlow.run
              │                       └─ pool.acquire() → TestExecutor.execute
              │                             ├─ setup()                  (optional)
              │                             ├─ watchers.start()         (daemon threads)
              │                             ├─ chain_runners            (Railway DSL)
              │                             ├─ watchers.stop()
              │                             └─ teardown()               (always)
              ├─ campaigns (main)
              │  (skipped if a smoke failed)
              │
SUT   ────────┼────────────────────────────────────────────────────────────
              │
              ▼
       Selenium WebDriver ⇄ real browser
       sometimes: OTP HTTP GET + Redis (on the ocarina-example side)
              │
              ▼
       (6) run_plugins(results)
              ├─ generate_docx_proof  (reads the log tree, builds .docx files)
              ├─ generate_json_results (serializes results to .json)
              ├─ others if declared (parallelized via ThreadPoolExecutor)
              │
              ▼
       (6') post_exec(results)
              ├─ pretty_print_results (ANSI, hierarchical)
              └─ has_test_cycle_failed → sys.exit(1) if applicable

Step-by-step#

(1) Parse CLI#

create_selenium_auto_cli_store() detects the OS via platform.system():

01.03 — KISS and ostentatious complexity

Wed, 20 May 2026 00:00:00 +0000

01.03 — KISS and ostentatious complexity#

The criticism that landed#

First public feedback Ocarina got, systematic per the author:

The first “criticisms” were often the same: “You’re bragging about something that’s very simple.”

The Holy Book takes its time answering. Three pillars: the operating nature of simplicity, the simple ≠ unsophisticated distinction, and the rejection of every “creative” counter-proposal that came in.

Simple ≠ unsophisticated#

This is also why KISS (Keep it simple, stupid) is so misunderstood in the industry. Many assume “simple” means “unsophisticated.” It would be hard to misread a principle more thoroughly.

02.03.03 — The failure rail: NeutralAction*

Wed, 20 May 2026 00:00:00 +0000

02.03.03 — The failure rail: `NeutralAction*`#

Edge case in the builder: what happens when you chain an action onto an ActionChain that has already failed?

Why Neutral classes rather than a user-side `if`#

When you chain an action onto an already-failed ActionChain, you slide into three Neutral classes that honor the same API but do nothing.

Picture the DSL without this. User code would look like:

chain = act1.failure(h).success(h).execute()

if chain.is_ok():
    chain = chain.then(act2).failure(h).success(h).execute()

if chain.is_ok():
    chain = chain.then(act3).failure(h).success(h).execute()

Imperative, unreadable, and the whole point of the DSL is gone. The neutral rail keeps the writing flat:

02.04.03 — .otherwise(...) and _any_of

Wed, 20 May 2026 00:00:00 +0000

02.04.03 — `.otherwise(...)` and `_any_of`#

How Ocarina expresses a logical OR between two predicates without breaking error aggregation.

The problem#

Concrete case: you want “age == 18 OR age <= 65.” The ROP/invariants syntax is a strict chain of assertions, and every .assert_that() is an AND. How do you express an OR?

Code#

def otherwise(self, fallback: Predicate[T], *, msg: str | None = None) -> ValidationAssertBlock[T]:
    if self._last_predicate is None:
        raise RuntimeError("otherwise() must follow assert_that().")

    fallback_with_msg = _with_msg(fallback, msg, self._name)
    combined = _any_of(
        self._last_predicate, *([*self._otherwise_predicates, fallback_with_msg])
    )
    self._chain._steps.pop()                    # replace the last step
    self._chain.add_assertion(self._value, combined, self._name)
    self._last_predicate = combined
    self._otherwise_predicates.append(fallback_with_msg)
    return self

Guard: otherwise() has to follow an assert_that(). With no prior predicate it raises. (In practice the type-checker already rules it out — ValidationStartBlock.otherwise doesn’t exist.)
Combination: combine previous predicate + all accumulated otherwise predicates + the new one, via _any_of. Result: a composite predicate.
Step replacement: pop the last step from _ValidationChain and push the combined one. Otherwise the original predicate AND the combined one would both be present, and the original error would resurface.

`_any_of`#

def _any_of[T](*predicates: _PredicateWithMsg[T]) -> _PredicateWithMsg[T]:
    def _try_predicate(p: _PredicateWithMsg[T], value: T) -> InvariantViolationError | None:
        try:
            p(value)
        except InvariantViolationError as exc:
            return exc
        else:
            return None

    def combined(value: T) -> None:
        errors = []
        for p in predicates:
            error = _try_predicate(p, value)
            if error is None:
                return                              # ✅ one predicate passes → all pass
            errors.append(error)

        formatted_error_messages = "  | " + "\n  | ".join(str(e) for e in errors)
        msg = (
            f"All predicates failed for value {value!r}.\n"
            "» At least one of the following conditions must be satisfied:\n"
            f"{formatted_error_messages}"
        )
        raise InvariantViolationError(msg)

    return _PredicateWithMsg(combined)

First success wins: the moment one predicate passes, combined returns None.
All fail: build an aggregated message listing every failure, separated by |.
Result is a _PredicateWithMsg: plug it back into the chain like any other predicate.
Aggregation is recursive: 3 successive otherwise() calls fold (P_orig OR P_otherwise1 OR P_otherwise2 OR P_otherwise3) into one predicate.

Example#

validate(age, name="age")
    .assert_that(is_equal_to(18), msg="Must be 18 or at most 65")
    .otherwise(is_less_than_or_equal_to(65), msg="Must be 18 or at most 65")
    .execute()
    .raise_if_invalid()

If age == 18: is_equal_to(18) passes → OK.
If age == 30: is_equal_to(18) raises, is_less_than_or_equal_to(65) passes → OK.
If age == 70: both raise → InvariantViolationError with:

age: All predicates failed for value 70.
» At least one of the following conditions must be satisfied:
  | age: Must be 18 or at most 65
  | age: Must be 18 or at most 65

(The duplicated message comes from passing the same msg= twice. Intentional here — we want a single statement of intent.)

02.05.03 — TestFlow[Driver] — retry policy

Wed, 20 May 2026 00:00:00 +0000

02.05.03 — `TestFlow[Driver]` — retry policy#

Source file: src/ocarina/dsl/testing/internals/test_flow.py

One job: for a single Test, run the retry loop, acquire a fresh driver per attempt, apply the backoff policy.

Why an intermediate level between `TestSuite` and `TestExecutor`#

Level	Doesn’t know about
`TestExecutor`	Retries, the driver pool
`TestFlow`	Inter-test concurrency, suite-level aggregation
`TestSuite`	One attempt’s execution, retries

A genuinely strict separation. TestFlow is the only level that knows both the pool and the retry policy — combining them is its whole job.

02.10.03 — Screenshotter[TDriver]

Wed, 20 May 2026 00:00:00 +0000

02.10.03 — `Screenshotter[TDriver]`#

Source file: src/ocarina/infra/screenshotter.py

Generic, thread-safe screenshot utility. Driver-agnostic via a Protocol, configurable via a dataclass. Supports burst.

`Protocol`#

class ScreenshotDriver(Protocol):
    def save_screenshot(self, path: str) -> bool:
        """Save standard viewport screenshot."""

That’s it. Any object with save_screenshot(path: str) -> bool qualifies. Selenium WebDriver has it natively (driver.save_screenshot), Playwright can be wrapped, a fake driver in tests exposes it trivially.

`ScreenshotterConfig[TDriver]`#

@dataclass(frozen=True)
class ScreenshotterConfig[TDriver: ScreenshotDriver]:
    output_dir: Path
    file_ext: str = ".png"
    health_check: HealthCheck[TDriver] | None = None
    save_full_page: SaveFullPageScreenshot[TDriver] | None = None
    default_burst_delay: float = 0.5
    max_filename_retries: int = 500
    uuid_length: int = 8

Field	Type	Role	Default
`output_dir`	`Path`	Screenshot directory	—
`file_ext`	`str`	Extension (`.png`, `.jpg`)	`.png`
`health_check`	`HealthCheck[TDriver] \| None`	`(driver) -> None` that raises if the driver is dead	`None`
`save_full_page`	`SaveFullPageScreenshot[TDriver] \| None`	`(driver, path) -> bool` for full-page screenshots (Firefox only)	`None`
`default_burst_delay`	`float`	Delay between 2 shots in burst mode	`0.5`s
`max_filename_retries`	`int`	Max attempts to generate a unique name	`500`
`uuid_length`	`int`	UUID suffix length in the name	`8`

Immutable. Configure once, ship.

02.11.03 — Auto CLI store + flags + validation

Wed, 20 May 2026 00:00:00 +0000

02.11.03 — Auto CLI store + flags + validation#

Source file: src/ocarina/opinionated/cli/selenium/create_cli_store.py

Flags#

Flag	Default	Type	Validation
`--driver-path`	`""`	`str`	`is_file` (except `--browser safari`)
`--profile-path`	`None`	`str`	`is_none` OR `is_dir`
`--browser`	`None` (required)	`str`	argparse `choices` (per OS)
`--not-headless`	`False` (= headless by default)	`bool` (`store_true`)	phantom
`--workers`	`5`	`int`	`is_positive` + `is_not_zero`
`--logger`	`"terminal+file"`	`str`	`choices=LOGGERS_CHOICES`
`--wait-timeout`	`10`	`int`	`≤ 60`, `> 0`
`--dont-force-delete-tmp-dirs`	`False`	`bool` (`store_true`)	phantom
`--only`	`[]`	`list[str]` (`nargs="+"`)	phantom + mutex
`--exclude`	`[]`	`list[str]` (`nargs="+"`)	phantom + mutex

_DEFAULT_WORKERS_AMOUNT = 5
_DEFAULT_LOGGER: SupportedLogger = "terminal+file"
_DEFAULT_BROWSER_AUTOMATION_TIMEOUT = 10
_MAX_BROWSER_AUTOMATION_TIMEOUT = 60

`Literal[...]`#

type SeleniumCliStoreKeys = Literal[
    "driver_path", "profile_path", "browser", "headless", "workers",
    "logger", "wait_timeout", "force_delete_tmp_dirs", "only", "exclude",
]

These keys are the store’s whole vocabulary. Call-sites use them: store.get("workers"), store.get("browser"), etc.

03.03 — Lazy evaluation

Wed, 20 May 2026 00:00:00 +0000

03.03 — Lazy evaluation#

In Ocarina, nothing is executed until you explicitly trigger it. That’s what makes scenarios composable as values.

Zzz#

Location	Form	Trigger
`ChainRunner[T]`	`Thunk[ActionChain[T]]`	`runner.run()`
`validate(...)`	`ValidationStartBlock` / `ValidationAssertBlock`	`.execute()`
`match_page(...)`	returns a `ChainRunner[Any]`	`.run()` (via the surrounding chain)
`Watcher.callback`	`Callable[[Watcher], None]`	`_loop` when `start()` is called
`logger.set_prefix(thunk)`	`Thunk[str]`	recomputed at each log call
`Scenario.setup` / `teardown`	`Effect`	called by `TestExecutor`
`bootstrap(post_exec=...)`	`Callable[[TestCycleResults], None]`	called after `run_plugins`
`CliBuilder(effects_factory=lambda ns: (...))`	`Effects`	called after the argparse parse
`test_scenario: TestScenario[Driver]`	`Callable[[Driver, ILogger], Scenario[Driver]]`	called by `Test.spawn`
`dispatch[mode]()` in `TestCycle.run_all`	dict of `Thunk[bool]`	called on lookup

`ChainRunner`#

runner = drive_page(act1, act2, act3)        # ⚠️  nothing executed
# … later …
chain = runner.run()                         # ▶︎  execution

Capability	Without laziness	With laziness
Store a scenario in a variable	impossible (already executed)	trivial
Multiply `[runner] * 5`	executes once, you get 5 refs to the result	executes 5 times
Pass a `runner` to another `runner` (composition)	impossible	trivial
Reorder `act`s in a test refactor	hard	trivial

`validate(...).execute()`#

v = validate(value, name="x").assert_that(is_positive).assert_that(is_not_zero)
# … you can compose …
combined = chain_validations(v, other_validation)
# … nothing executed so far …
combined.execute().raise_if_invalid()        # ▶︎  execution + aggregation

That’s how _ValidationChain collects every error before raising a single one (AggregateInvariantViolationError).

04.03 — Scenario tests (pytest + allure)

Wed, 20 May 2026 00:00:00 +0000

04.03 — Scenario tests (pytest + allure)#

15 test_*.py files in tests/scenarios/ cover the DSL, orchestration and the Playwright actor. Dynamic tests.

Listing#

tests/scenarios/
├── conftest.py                              # FakeDriver, RecordingPOM, make_*
├── test_railway_and_action_chain.py         # create_act, drive_page, Result, ChainRunner
├── test_match_page.py                       # match_page / when (first/last branches, exceptions)
├── test_validate.py                         # validate, assert_that, otherwise, then, chain_validations
├── test_invariants_properties.py            # hypothesis (see 06-hypothesis-properties)
├── test_drivers_pool.py                     # WebDriversPool (acquire, warmup, shutdown, semaphore leaks)
├── test_screenshotter.py                    # Screenshotter (single shot, burst, healthcheck, threadsafety)
├── test_driver_builder.py                   # DriverBuilder (profile tmp dir, dispose)
├── test_watcher.py                          # Watcher (start, stop, callback errors swallowed, dedup cache)
├── test_playwright_driver_actor.py          # PlaywrightDriver actor (sync_playwright mocked, no browser)
├── test_playwright_adapter.py               # real-browser smoke (skipped if no Chromium installed)
├── test_test_suite.py                       # TestSuite (parallel, saturation, only/exclude, transient_errors)
├── test_test_cycle_and_bootstrap.py         # TestCycle, mode fail-fast vs wait-for-all, bootstrap
├── test_loggers_and_reports.py              # PrintLogger, FileLogger, pretty_print, JSON
├── test_docx_tests_proofs.py                # generate_docx_proof (parse logs, insert images)
└── test_env.py                              # smoke test: versions, Python 3.14+

Example internal test#

@allure.epic("Railway / action chain")
@allure.feature("Action chain")
@allure.tag("act", "handlers", "happy-path")
@allure.severity(allure.severity_level.CRITICAL)
@allure.label("layer", "unit")
@allure.title("A successful act reports success; the success handler fires once")
def test_success_act_fires_success_handler() -> None:
    pom = RecordingPOM()
    calls = {"success": 0, "failure": 0}

    chain = (
        create_act(pom, lambda p: p.step("click"))
        .failure(lambda _: calls.__setitem__("failure", calls["failure"] + 1))
        .success(lambda: calls.__setitem__("success", calls["success"] + 1))
        .execute()
    )

    assert chain.is_ok()
    assert pom.calls == ["click"]
    assert calls == {"success": 1, "failure": 0}

Assertion	Target
`chain.is_ok()`	Public API
`pom.calls == ["click"]`	Observable POM behavior (recording)
`calls == {"success": 1, "failure": 0}`	Right handler called

Allure annotations#

Category	Typical values
`epic`	“Railway / action chain”, “Invariants”, “Orchestration”, “Watcher”, “Drivers pool”, “Reports”, “Match page”
`feature`	“Action chain”, “Validate”, “TestSuite”, “TestCycle”, “Bootstrap”, “Pretty print”, “JSON”, “DOCX proofs”
`tag`	“act”, “handlers”, “happy-path”, “error-handling”, “retry”, “transient”, “smoke”, “skip”, “saturation”, “parallel”
`severity`	CRITICAL > NORMAL > MINOR > TRIVIAL
`label("layer", ...)`	“unit”, “integration”

`test_test_suite.py`#

Tests pass in sequential mode (max_workers=1).
Tests pass in parallel mode (max_workers=N).
--only / --exclude filtering.
--only + --exclude mutex.
Saturation: tests cloned with [COPY N].
Retries on transient errors.
Setup failure → SKIPPED when every attempt fails at setup.
A skipped=True test stops immediately.
Guardrails (unique names, unique IDs).
take_screenshot called on fail if autoscreen_on_fail.
Exact attempt counting on max_retries (one test covers the loop edge).

`test_match_page.py`#

Case	Assertion
First branch matches → executed	`chain.is_ok()`, later branches not evaluated
Second branch matches → executed	id.
No branch matches	`NoMatchingBranchError` in the `Fail`
Branch matches, but its `then` fails	`Fail` propagated
`condition` raises an ordinary `Exception`	Treated as `False`, later branches tried
`condition` raises an exception from the `raised_exceptions` tuple	Re-raise
Branch `then=[]` matches	`Ok(None)`
`match_page` in the middle of a `test_chain`	Short-circuits if failed

`test_drivers_pool.py`#

Uses a FakeDriverFactory that can be configured to raise / block / sleep, and counts its calls.

05.03 — The fake useAuth + MFA OTP

Wed, 20 May 2026 00:00:00 +0000

05.03 — The fake `useAuth` + MFA OTP#

Igoristan’s useAuth hook is deliberately fake. Two mechanics to exercise Ocarina’s replay and worker coordination: a 10% random failure and an optional MFA OTP.

Code#

// src/hooks/useAuth.ts
const VALID_PASSWORD = "figatellu";
const NOT_AUTHENTICATED = -1;
const AUTHENTICATED_WITHOUT_MFA = 1;
const AUTHENTICATED_WITH_MFA = 2;

// * ... This is FAKED
export const useAuth = () => {
  const [_isAuthenticated, setIsAuthenticated] = useLocalStorage(
    "isAuthenticated",
    NOT_AUTHENTICATED,
  );
  const [isLoading, setIsLoading] = useState(true);

  const isAuthenticated = useCallback(
    () => _isAuthenticated !== NOT_AUTHENTICATED,
    [_isAuthenticated],
  );
  const isAuthenticatedWithMFA = useCallback(
    () => _isAuthenticated === AUTHENTICATED_WITH_MFA,
    [_isAuthenticated],
  );
  const logout = useCallback(
    () => setIsAuthenticated(NOT_AUTHENTICATED),
    [setIsAuthenticated],
  );

  useEffect(() => {
    const delay = 500 * randint(1, 5); // ◄── random delay 0.5–2.5s
    const timer = setTimeout(() => setIsLoading(false), delay);
    return () => clearTimeout(timer);
  }, []);

  const login: LoginFn = ({ pre = false, password, withMFA }) => {
    if (password === VALID_PASSWORD && Math.random() < 0.9) {
      // ◄── 10% fail despite correct password
      if (!pre) {
        setIsAuthenticated(
          withMFA ? AUTHENTICATED_WITH_MFA : AUTHENTICATED_WITHOUT_MFA,
        );
      }
      return true;
    }
    return false;
  };

  return { isAuthenticatedWithMFA, isAuthenticated, isLoading, logout, login };
};

Mechanics#

1. `LocalStorage`#

const [_isAuthenticated, setIsAuthenticated] = useLocalStorage(
  "isAuthenticated",
  NOT_AUTHENTICATED,
);

Three values: -1 (not authenticated), 1 (no MFA), 2 (with MFA).
Persisted in localStorage, easy to inspect for testing / manual debugging.

06.03 — GET /api/otp-history

Wed, 20 May 2026 00:00:00 +0000

06.03 — `GET /api/otp-history`#

Source file: api/otp-history.ts

Code#

import type { NextRequest } from "next/server";
import redis from "../lib/redis";
import isAuthorized from "../lib/isAuthorized";

export const config = { runtime: "edge" };

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, OPTIONS",
  "Access-Control-Allow-Headers": "x-api-key, Content-Type",
} as const;

export default async function handler(request: NextRequest) {
  if (request.method === "OPTIONS") {
    return new Response(null, { status: 200, headers: corsHeaders });
  }

  if (!isAuthorized(request)) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { "Content-Type": "application/json", ...corsHeaders },
    });
  }

  let cursor = "0";
  const allEvents = [];
  const BATCH_SIZE = 100;

  do {
    const [newCursor, keys] = await redis.scan(cursor, {
      match: "otp:*",
      count: BATCH_SIZE,
    });
    cursor = newCursor;

    if (keys.length > 0) {
      const values = await redis.mget(...keys);
      allEvents.push(...values.filter(Boolean));
    }
  } while (cursor !== "0");

  return new Response(JSON.stringify(allEvents), {
    headers: { "Content-Type": "application/json", ...corsHeaders },
  });
}

Redis `SCAN` mechanics#

let cursor = "0";
const allEvents = [];
const BATCH_SIZE = 100;

do {
  const [newCursor, keys] = await redis.scan(cursor, {
    match: "otp:*",
    count: BATCH_SIZE,
  });
  cursor = newCursor;

  if (keys.length > 0) {
    const values = await redis.mget(...keys);
    allEvents.push(...values.filter(Boolean));
  }
} while (cursor !== "0");

cursor = "0" (initialization).
Loop:
- SCAN <cursor> MATCH otp:* COUNT 100 returns [newCursor, keys].
- If keys non-empty: MGET k1 k2 ... fetches the values.
- cursor = newCursor.
We stop when cursor === "0" (cycle complete).

Why SCAN rather than KEYS?

07.03 — Dashboard login scenarios

Wed, 20 May 2026 00:00:00 +0000

Three families: happy paths, unhappy paths, data-driven multi-login. All exercise the 10%-fail useAuth and OTP coordination.

`dashboard_login`#

# src/tests/campaigns/dashboard_login.py
def create_igoristan_login_campaign(*, drivers_pool: SeleniumWebDriversPool) -> TestCampaign:
    return TestCampaign(
        name="Dashboard login",
        suites=[
            create_igoristan_login_happy_paths_test_suite(drivers_pool=drivers_pool),
            create_igoristan_login_unhappy_paths_test_suite(drivers_pool=drivers_pool),
            create_igoristan_login_data_driven_test_suite(drivers_pool=drivers_pool),
        ],
    )

Happy paths#

# src/tests/suites/dashboard/access/happy_paths.py
def create_igoristan_login_happy_paths_test_suite(*, drivers_pool) -> TestSuite:
    return TestSuite(
        name="Login happy paths",
        tests=[
            test_dashboard_login_without_otp_happy_path,
            test_dashboard_login_with_otp_happy_path,
            test_dashboard_login_page_back_to_igoristan_button,
        ],
        drivers_pool=drivers_pool,
    )

def dashboard_login_without_otp_happy_path(driver, logger):
    dashboard_creds = create_env_getters().get_credentials("dashboard")
    on_dashboard_login_page = DashboardLoginPage(driver=driver)
    on_dashboard_welcome_page = DashboardWelcomePage(driver=driver)

    just_log_error = create_just_log_error(logger=logger)
    log_error_with_current_url = create_log_error_with_current_url(logger=logger, driver=driver)
    just_log_success = create_just_log_success(logger=logger)
    log_success_with_current_url_and_take_screenshot = create_log_success_with_current_url_and_take_screenshot(...)

    retries_amount = max(get_max_workers(), 10)

    return [
        drive_page(
            act(on_dashboard_login_page, open_dashboard_login_page)
                .failure(just_log_error("Failed to open the dashboard login page..."))
                .success(just_log_success("Opened the dashboard login page!")),
            act(on_dashboard_login_page, verify_dashboard_login_page)
                .failure(log_error_with_current_url("Failed to verify..."))
                .success(log_success_with_current_url_and_take_screenshot("Verified!")),
            act(on_dashboard_login_page,
                login_without_otp_and_with_retries(dashboard_creds, retries_amount, logger=logger))
                .failure(just_log_error("Failed to connect to the dashboard without OTP..."))
                .success(just_log_success("Connected to the dashboard!")),
        ),
        drive_page(
            act(on_dashboard_welcome_page, verify_dashboard_welcome_page)
                .failure(log_error_with_current_url("Failed to verify..."))
                .success(log_success_with_current_url_and_take_screenshot("Verified!")),
        ),
    ]

retries_amount = max(get_max_workers(), 10): at least 10 internal login retries to beat the 10% random failure.
login_without_otp_and_with_retries(creds, retries_amount, logger=logger): closure capturing creds, retry count, and logger. Returns Callable[[DashboardLoginPage], DashboardLoginPage].
2 drive_pages: login page then welcome page. Each opens, verifies, screenshots.
Log factories everywhere: no inline lambdas.
SeleniumTitleMixin: get_current_title() feeds act’s on_failure hook.

def dashboard_login_with_otp_happy_path(driver, logger):
    # ... same setup ...

    cache = in_memory_cache_with_30m_ttl
    fresh_cache_key_for_username = reserve_free_cache_key(cache)
    fresh_cache_key_for_otp_send_button_click_date = reserve_free_cache_key(cache)

    return [
        drive_page(
            act(on_dashboard_login_page, open_dashboard_login_page)...,
            act(on_dashboard_login_page, verify_dashboard_login_page)...,
            act(on_dashboard_login_page,
                start_to_login_with_otp_and_with_retries(
                    dashboard_creds, retries_amount,
                    cache=cache, logger=logger,
                    username_cache_key=fresh_cache_key_for_username,
                    otp_send_button_click_date_cache_key=fresh_cache_key_for_otp_send_button_click_date,
                ))...,
            act(on_dashboard_login_page, verify_otp_screen)...,
            act(on_dashboard_login_page,
                type_otp_with_retries(
                    retries_amount,
                    cache=cache, logger=logger,
                    username_cache_key=fresh_cache_key_for_username,
                    otp_send_button_click_date_cache_key=fresh_cache_key_for_otp_send_button_click_date,
                ))...,
        ),
        drive_page(
            act(on_dashboard_welcome_page, verify_dashboard_welcome_page)...,
            act(on_dashboard_welcome_page, click_on_go_to_nested_page_btn)...,
        ),
        drive_page(
            act(on_dashboard_protected_page, verify_dashboard_protected_page)...,
        ),
    ]

Three drive_pages, five acts in the first. L1 cache + reserved keys share values between acts (see 08-caches-locks.md).

08.03 — Documentation

Wed, 20 May 2026 00:00:00 +0000

08.03 — Documentation#

The AI project is the most documented in the Ocarina ecosystem.

Listing#

Document	Status	Audience
`CLAUDE.md`	Claude ↔ project working contract	Claude + any contributor
`CURA_FRD.md`	Reconstructed spec	Maintainers, stakeholders
`CURA_TEST_STRATEGY.md`	Test strategy	Maintainers
`IDENTIFIED_GAPS.md`	Technical inventory of gaps	Maintainers

`CLAUDE.md`#

Key documents: points to README.md, CURA_FRD.md, CURA_TEST_STRATEGY.md, IDENTIFIED_GAPS.md, CLAUDE.local.md.
Project: 2 sentences on the project (CURA, Python 3.14+, demo creds).
Project philosophy: “No tricks or hacks. Teach the pattern, not the symptom.”
CLAUDE.local.md template: what the gitignored file should contain.
Layout: full src/ tree, audited (shell command that verifies CLAUDE.md and the real tree stay in sync).
Ocarina hierarchy: reminder Test → Suite → Campaign → Cycle.
Test strategy: cycle structure, smoke gate, taxonomy.
Running tests: CLI commands.
Reports and screenshots: “one screenshot per drive_page” rule.
Scenario fragments: when to extract a fragment.
Data-driven tests: when to use the pattern, naming conventions.
Shared mixins: SeleniumBackAndForwardNavigationMixin.
Conventions: 12 concrete rules (TYPE_CHECKING guard, log factories, etc.).
Hard-won rules: rules drawn from experience, with past examples.

Hard-won rules#

“Verify SUT behaviour — don’t theorise”#

CURA is open source. Before building on a server-side claim, read the PHP:

09.03.03 — Black-hat skills

Wed, 20 May 2026 00:00:00 +0000

09.03.03 — Black-hat skills (6)#

Ideations of business logic vulnerabilities — no execution: “security testing is functional and static, never active”.

Listing (potentially non-exhaustive)#

Skill	Target
`business-logic-vulnerability-ideation`	Break the product through legitimate-looking but malicious usage paths
`incoherence-attack-ideation`	Each step taken alone looks innocent; but combinations of these steps can cause an inconsistency in the system
`persistence-attack-ideation`	Repeated attempts at a blocked action
`permission-appropriateness-audit`	Is the access model itself appropriate?
`bfcache-exposure-ideation`	BFCache attacks
`lateral-resource-ideation`	IDOR via the address bar only

Perimeter#

All these skills imagine attacks the AI could phrase.

10.03 — ocarina-example workflows

Wed, 20 May 2026 00:00:00 +0000

10.03 — `ocarina-example` workflows#

See also ../07-ocarina-example/11-ci.md

Overview#

Workflow	Trigger	OS	Effect	Note
`main_ci.yml`	push/PR main, dispatch	ubuntu + windows × py 3.14	`make check-coding-style` (mypy + ruff).	Fast PR gate
`dev_ci.yml`	push dev, dispatch	ubuntu × py 3.14	Same	For dev branches
`e2e.yml`	`workflow_dispatch` (env `OC`)	ubuntu + Redis service + Firefox + geckodriver 0.35.0	Full suite run + upload `.screenshots/` `.ocarina_logs/` `.reports/`	Manual only

vs `ocarina/main_ci.yml`#

Aspect	`ocarina/main_ci.yml`	`ocarina-example/main_ci.yml`
Unit tests	Yes (pytest + cram)	No
Allure history	Yes	No
GitHub Pages deploy	Yes (Allure report)	No
OS matrix	Yes (ubuntu + windows)	Yes (same)
Python matrix	Optional (3.14 or 3.14+3.15)	No (3.14 only)

ocarina tests itself (unit tests) in CI. ocarina-example only runs static checks in CI; its e2e tests are fired on demand via e2e.yml.

11.03 — Explicit refusals

Wed, 20 May 2026 00:00:00 +0000

11.03 — Explicit refusals#

Synthesis of refusals scattered across the Holy Book.

Summary table#

Refusal	Reason	Reference
`async`/`await`	Selenium synchronous, Requests synchronous; readability; no point introducing an event-loop	Holy Book
pytest plugin	Independence, ISTQB fidelity	Ocarina `README`
Text DSL (Robot, Gherkin)	No translation layer	Holy Book
Reactive programming	Static scenarios, in-memory cache suffices	Holy Book
Tricks and hacks	“Teach the pattern, not the symptom”	`CLAUDE.md` ai-example
“Stylish” contributions	“It’s my car”	Holy Book
Active security tests	Functional and static only, never attacks	`CLAUDE.md` ai-example

1. Refusal of `async`/`await`#

Central quote:

12.03 — YTCracker, Nerdcore, Digital Gangster

Wed, 20 May 2026 00:00:00 +0000

12.03 — YTCracker, Nerdcore, Digital Gangster#

Bryce Case Jr., a single man, connects four universes: the US hacker scene (1999-2005), the birth of Nerdcore (nerd hip-hop, 2005-2008), Digital Gangster (forum 2005-2017), and crypto culture (from 2013 onward, notably with Bitcoin Baron). The Holy Book quotes him several times.

1. Identity#

Field	Value
Name	Bryce Case Jr.
Born	August 23, 1982, La Mirada, California
Alias	YTCracker (pronounced “whitey cracker”)
Status	Formerly black hat, now white hat (cybersec consultant + musician)

The pseudo “YTCracker” is pronounced whitey cracker. It combines “Yours Truly”, the name of a character in Neal Stephenson’s cyberpunk novel Snow Crash, and the term cracker — the one who breaks into computer systems. Bryce Case himself explained this etymology in several interviews.

00.04 — Relations between the six repositories

Wed, 20 May 2026 00:00:00 +0000

00.04 — Relations between the six repositories#

Every edge of the graph is a contract — a secret, a URL, a payload type, or a version. One pair per section below.

`ocarina` ↔ `ocarina-example`#

Direction	Mechanism
`ocarina` → `ocarina-example`	`pip install ocarina` from PyPI
`ocarina-example` → `ocarina`	None (the example pushes nothing)

The example writes its own adapters on top of the framework:

lib/ext/ocarina/adapters/agnostic/act.py → adds an on_failure hook that turns an HTTP error page (title matched by ERROR_PAGE_REGEX) into HttpErrorPageReachedError.
lib/ext/ocarina/adapters/agnostic/match_page.py → create_match_page(raised_exceptions=transient_errors).
lib/ext/ocarina/adapters/agnostic/env_getters.py → typed EnvGetters[_CredsKeys, _ValuesKeys].
lib/ext/ocarina/adapters/selenium/test_suite.py → pins max_retries_per_test=8, transient_errors=..., autoscreen_on_fail=True, propagates --only/--exclude.
lib/ext/ocarina/adapters/selenium/test_campaign.py → pins max_workers=get_max_workers().

`ocarina` ↔ `ocarina-with-ai-example`#

pip install . ruff mypy mypy-extensions typing-extensions pre-commit — the AI example pins its dep in pyproject.toml: ocarina>=1.0.3.
act adapter is minimal here. No on_failure (CURA doesn’t throw deliberately random HTTP error pages). See ../08-ai-example/
create_drivers_pool adapter is overridden to build a clean Chrome (password manager off, leak detection off). See ../08-ai-example/06-data-gaps.md

`ocarina-example` ↔ `igoristan`#

Direction	Contract	Detail
`ocarina-example` → `igoristan`	Public URLs	Everything goes through `https://mojo-molotov.github.io/igoristan/<route>`
`igoristan` → `ocarina-example`	none (the SUT doesn’t know it’s being tested)	—

src/constants/pages/:

01.04 — Citations and claimed influences

Wed, 20 May 2026 00:00:00 +0000

01.04 — Citations and claimed influences#

The references cited in the Holy Book aren’t neutral — they set Ocarina’s theoretical frame. We cut them by axis here, then offer the overall reading.

Technical axis — Functional programming, types, languages#

Influence	Origin	Relation to Ocarina
Railway Oriented Programming (ROP)	Scott Wlaschin (F#), a well-known pattern in functional programming	The heart of the framework. `Result[T] = Ok[T] \| Fail`, short-circuit, fluent builder. See `../02-ocarina/03-railway/`.
λ-calculus (1930)	Alonzo Church	Cited as the invention that makes possible the “clean formalization” Ocarina pursues: “What has been on our minds since the 1930s, since the invention of λ-calculus, is finally scalable to the degree we always wanted it to be.”
McCulloch & Pitts (1943)	First formalization of the artificial neuron	Cited as a reminder that the real progress in AI is old and continuous, against the recent hype.
Python type system (PEP 695)	PEP 695 (Python 3.12+)	Prerequisite for the generic parametric typing that structures Ocarina (`TestSuite[Driver]`, `Result[T]`, etc.). See `../03-functional/06-pep-695-generics.md`.

Cultural axis — Anti-narcissism, simplicity, KISS done right#

Influence	Citation	Why
Terry Davis (“the smartest programmer that’s ever lived”)	“An idiot admires complexity, a genius admires simplicity, a physicist tries to make it simple…”	Anti–ostentatious complexity argument; cornerstone of the “First feedbacks” chapter.
Lao-Tzu	“To attain knowledge, add things every day. To attain wisdom, remove things every day.”	A subtractive method: what remains after elimination.
Antoine de Saint-Exupéry	“Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.”	Western restatement of the previous one. Closes the “First scenarios” chapter.
Alan Watts	“Muddy water is best cleared by leaving it alone.”	Cited at the end of the “First jutsus” chapter: legitimizes a design that refuses certain features (reactivity, async). Legitimizes stepping out of the “geek tricks” ecosystem.
Rainer Maria Rilke	“Live the questions now. Perhaps then, someday far in the future, you will gradually, without even noticing it, live your way into the answer.”	Closes the “First steps” chapter. Stance toward practice: mastery comes from use.
Marcel Proust	“For the writer as well as for the painter, style is not a question of technique, but of vision.”	Closes the “Extensibility” chapter. Justifies the refusal to impose a DSL: vision (POMs + actions) trumps technique (a format).

Political axis — Code, sovereignty, anti–startup nation#

Influence	Origin	Relation to Ocarina
*Code is Law*	Lawrence Lessig (1999), reclaimed by Ethereum (2015) as a positive ideal	Cited as the stance against “democratic governance of code”. The project claims it: “Once again, with AI, that sorely missing digital body, let us scream it, as loud as we screamed ‘HACK THE PLANET’ back in ‘99: CODE IS LAW.”
DHH — I won’t let you pay me for my open source	David Heinemeier Hansson, personal blog	Cited to legitimize refusing unaligned contributions (“Fuck You” references DHH’s famous slide).
Paul Graham — Haters	PG essay (`paulgraham.com/fh.html`)	Grounds the decision to “never waste time arguing when it isn’t worth it”.
Yegor Bugayenko — Prompt	The quote “Retry flaky blocks.”	Grounds the `transient_errors` + linear retry policy (`TestFlow`). Read also: Angry Tests.
The DAO hack (2016)	Hack of The DAO on Ethereum	Cited to point out that it was bugs (“damned bugs, because of damned devs”) that set Code is Law back, hence the importance of typing and rigor.
Lee Robinson (ex-Vercel)	December 2025: Cursor replacing Sanity with Markdown files + AI	Backs the “return to raw data”.
Cluely (Roy Lee)	Cited as an illustration of entrepreneurial bullshit to avoid	Explicit contrast with the Ocarina philosophy.

Identity / underground axis#

Influence	Origin
LulzSec — “In the Lulzboat, salute, bitch, and show some respect.”	AntiSec (YTCracker, 2011)
*“We Can Do All What You Can’t Do”*	YogyaCarderLink
YTCracker — Robots Will Definitely Take Your Job	SoundCloud link, background music of the “First feedbacks” chapter
“HACK THE PLANET” (1999)	Emblematic slogan of the 1990s hacker scene + AntiSec (YTCracker, 2011)
Zone-H	Historic web defacement archive
r/unixporn, r/AntiTaff	Subreddits

AI / modern tooling axis#

Influence	Origin	Relation to Ocarina
Claude Code	Anthropic	Reference tooling for the AI project (`ocarina-with-ai-example`). Cited several times as the “bridge” replacing DSLs.
IntelliCode (2018)	Microsoft	Cited as a temporal landmark (“we had already tasted it, well before IntelliCode”).
R., the silo’s mad scientist	Personal anecdote (a 2013 colleague, a private Emacs AI plugin)	Reminder that generative AI (“15,000 lines to delete to avoid writing 1,000”) existed before the public hype.
Prisma, Vercel, Cursor	SaaS ecosystem	Cited as practical cases of an AI-assisted return to raw data.

Overall coherence#

All these influences converge on three axes:

02.03.04 — chain_actions and ChainRunner

Wed, 20 May 2026 00:00:00 +0000

02.03.04 — `chain_actions` and `ChainRunner`#

Source file: src/ocarina/dsl/testing_with_railway/chain_actions.py

The primitive that makes the DSL “flat.” Without it, an N-step scenario is a staircase of .then(...).failure(...).success(...).execute(). With it, it’s a list.

“Parenthesis hell”#

Solution:
# Flat, readable syntax
runner = chain_actions(
    action1.failure(h1).success(h2),
    action2.failure(h3).success(h4),
    action3.failure(h5).success(h6)
)
chain = runner.run()  # Execute when ready
Benefits:

Lazy evaluation: Build chain without executing

Flat syntax: No deep nesting

Automatic short-circuiting: Stops on first failure

Composability: ChainRunner is a value

(Excerpt from the docstring.)

02.04.04 — .then(...) and chain_validations(...)

Wed, 20 May 2026 00:00:00 +0000

02.04.04 — `.then(...)` and `chain_validations(...)`#

Two distinct mechanisms to compose multiple validations into one.

`.then(new_value)`#

def then[U](self, new_value: U, *, name: str | None = None) -> ValidationStartBlock[U]:
    return ValidationStartBlock(new_value, self._chain, name)

Switches the type from T to U. The checker accepts the change.
Keeps the chain (self._chain). Past assertions stay in it; new ones stack on top.
Swaps the name: the name you pass to .then() is the one used for the next assertions, not the previous block’s.

Canonical use case#

validate(user, name="user")
    .assert_that(is_not_none)
    .then(user.email, name="user.email")
    .assert_that(is_email)
    .then(user.age, name="user.age")
    .assert_that(is_positive)
    .assert_that(is_less_than_or_equal_to(120))
    .execute()
    .raise_if_invalid()

Reads as: validate user, then user.email, then user.age. All pass → OK. One fails → every error rolls up into the AggregateInvariantViolationError.

02.05.04 — TestSuite[Driver] — parallelized engine

Wed, 20 May 2026 00:00:00 +0000

02.05.04 — `TestSuite[Driver]` — parallelized engine#

Source file: src/ocarina/dsl/testing/oc_test_suite.py

One job: run a sequence of Tests in parallel, handle saturation, ID filtering, and pre-execution invariant validation.

Constructor#

def __init__(
    self,
    *,
    name: str,
    tests: Sequence[Test[Driver]],
    create_logger: Thunk[ILogger],
    drivers_pool: WebDriversPool[Driver],
    take_screenshot: ITakeScreenshot[Driver],
    act_counter: ActCounter | None = None,
    transient_errors: tuple[type[Exception], ...] = (),
    copy_indicator: str = "COPY",
    put_space_after_copy_indicator: bool = True,
    max_retries_per_test: int | None = None,
    autoscreen_on_fail: bool = False,
    saturate_workers: bool | None = None,
    only_ids: Iterable[str] = (),
    exclude_ids: Iterable[str] = (),
) -> None:
    self._guards_on_invoke(tests)
    # ... assignments ...
    self._tests = filter_tests_by_ids(
        tests,
        only=only_ids,
        exclude=exclude_ids,
        logger=create_logger().set_prefix(lambda: f"{self.name}: filtering tests..."),
    )

Parameter	Type	Role	Default
`name`	`str`	Suite name (appears in logs & reports)	—
`tests`	`Sequence[Test[Driver]]`	List of tests to run	—
`create_logger`	`Thunk[ILogger]`	Logger factory	—
`drivers_pool`	`WebDriversPool[Driver]`	Shared pool	—
`take_screenshot`	`ITakeScreenshot[Driver]`	Callable `(driver, logger, category) -> None`	—
`act_counter`	`ActCounter \| None`	If `None` → `ThreadsBasedActCounter()`	`None`
`transient_errors`	`tuple[type[Exception], ...]`	Exceptions that trigger a retry	`()`
`copy_indicator`	`str`	Prefix for saturation-cloned tests	`"COPY"`
`put_space_after_copy_indicator`	`bool`	`[COPY 1]` (`True`) vs `[COPY1]` (`False`)	`True`
`max_retries_per_test`	`int \| None`	Max retries for a potentially flaky test	`None` → `_DEFAULT_MAX_RETRIES_PER_TEST` (8)
`autoscreen_on_fail`	`bool`	Automatically capture one or several screenshots (burst) on failure	`False`
`saturate_workers`	`bool \| None`	Clone tests to saturate every worker if the pool is large enough	`None` → cascade: suite > campaign > bootstrap
`only_ids`	`Iterable[str]`	`--only` filter	`()`
`exclude_ids`	`Iterable[str]`	`--exclude` filter	`()`

Guardrails#

At `init` time#

def _guards_on_invoke(self, tests: Sequence[Test[Driver]]) -> None:
    validate_test_runners_ids(tests=tests, name="tests").execute().raise_if_invalid()

→ Every test_id must be unique. Otherwise: AggregateInvariantViolationError. Raised at construction, before any execution attempt. Duplicate a test_id by accident and you find out instantly.

02.10.04 — ActCounter + ThreadsBasedActCounter

Wed, 20 May 2026 00:00:00 +0000

02.10.04 — `ActCounter` + `ThreadsBasedActCounter`#

Thread-local counter of act calls per attempt. Lets the report say “this test made 17 steps before dying at step 18.”

Interface#

# src/ocarina/infra/act_counter.py
class ActCounter:
    def get(self) -> int: ...
    def reset(self) -> None: ...
    def incr_act_call_count(self) -> None: ...

Default implementation#

# src/ocarina/opinionated/infra/act_counter.py
from threading import local

_thread_local = local()
_COUNTER_KEY: Final[str] = "ocarina_counter"


class ActCounter(_ActCounter):
    def get(self) -> int:
        return getattr(_thread_local, _COUNTER_KEY, 0)

    def reset(self) -> None:
        setattr(_thread_local, _COUNTER_KEY, 0)

    def incr_act_call_count(self) -> None:
        if not hasattr(_thread_local, _COUNTER_KEY):
            self.reset()
        setattr(_thread_local, _COUNTER_KEY, getattr(_thread_local, _COUNTER_KEY) + 1)

threading.local(): namespace where attributes are per thread. Each thread has its own value.
_COUNTER_KEY = "ocarina_counter": attribute key.
No lock: each thread only writes its own value, so no race.

Why thread-local rather than a shared counter + lock?#

Ocarina’s architecture says one thread = one test. We’ve got no appetite for a whole state monad — might as well park this “impurity” (still a piece of state) right here. That’s it.

02.11.04 — Loggers: PrintLogger, FileLogger, PrintAndFileLogger, MutedLogger

Wed, 20 May 2026 00:00:00 +0000

02.11.04 — Loggers: `PrintLogger`, `FileLogger`, `PrintAndFileLogger`, `MutedLogger`#

Source folder: src/ocarina/opinionated/loggers/

Four canonical ILogger implementations + a create_matching_logger factory. All opt-in.

`create_matching_logger`#

LOGGERS_CHOICES = ("terminal", "file", "terminal+file", "muted")

def create_matching_logger(mode: SupportedLogger) -> ILogger:
    if mode == "terminal":
        return PrintLogger()
    if mode == "file":
        return FileLogger(base_dir=get_default_log_dir())
    if mode == "terminal+file":
        return PrintAndFileLogger(base_dir=get_default_log_dir())
    if mode == "muted":
        return MutedLogger()
    raise ValueError(f"Unsupported logger mode: {mode}")

And:

def get_default_log_dir() -> Path:
    return Path.cwd() / ".ocarina_logs"

→ By default, logs land in .ocarina_logs/ at the user project root. Gitignored by convention.

`PrintLogger`#

class PrintLogger(ILogger):
    def __init__(self) -> None:
        self._prefix_thunk: Thunk[str] = lambda: ""
        self._domain_taxonomy: tuple[str, ...] = ("",)

    def set_prefix(self, prefix_thunk: Thunk[str]) -> Self:
        self._prefix_thunk = prefix_thunk
        return self

    def set_domain_taxonomy(self, taxonomy: tuple[str, ...]) -> Self:
        self._domain_taxonomy = taxonomy
        return self

    def raw(self, *args, stream=None, **kwargs) -> None:
        if stream is None:
            stream = sys.stdout
        print(*args, file=stream, **kwargs)

    def info(self, msg, *args, exc=None, **kwargs):
        self._print_log("[INFO]", msg, *args, exc=exc, stream=sys.stdout)
    # ... id. for critical / error / warning / debug / success / test_name ...

State: _prefix_thunk (Thunk) + _domain_taxonomy (tuple).
Output: sys.stdout (info, debug, success, test_name) or sys.stderr (critical, error, warning, exception).
Format: typically <prefix> [LEVEL] <message>, with ANSI colors if terminal.
cleanup(): no-op.

`FileLogger`#

@final
class FileLogger(PrintLogger):
    def __init__(
        self, *,
        base_dir: Path,
        with_flush_effect: bool = True,
        with_fallback_on_print_logger_when_no_taxonomy_effect: bool = True,
    ) -> None:
        self._base_dir = base_dir
        self._with_flush_effect = with_flush_effect
        self._with_fallback_on_print_logger_when_no_taxonomy_effect = (
            with_fallback_on_print_logger_when_no_taxonomy_effect
        )
        super().__init__()

    @property
    def _log_file_path(self) -> Path:
        if len(self._domain_taxonomy) == 1:
            folder_path = self._base_dir
            file_name = f"{self._domain_taxonomy[0]}.log"
        else:
            folder_path = self._base_dir.joinpath(*self._domain_taxonomy[:-1])
            file_name = f"{self._domain_taxonomy[-1]}.log"
        folder_path.mkdir(parents=True, exist_ok=True)
        return folder_path / file_name

Taxonomy	Folder	File
`("")`	—	→ Fallback to PrintLogger if enabled
`("annoncements",)`	`base_dir`	`annoncements.log`
`("e2e", "Login")`	`base_dir/e2e`	`Login.log`
`("e2e", "Login", "happy paths", "Login without OTP")`	`base_dir/e2e/Login/happy paths`	`Login without OTP.log`

The taxonomy is the folder tree. The DOCX reports (see 05-plugins-reports.md) walk it recursively and emit one .docx per test case.

03.04 — reduce / fold in Ocarina

Wed, 20 May 2026 00:00:00 +0000

03.04 — `reduce` / fold in Ocarina#

One reduce in the whole code base. But it’s the central reducer — it’s what makes chain_actions work.

Code#

# src/ocarina/dsl/testing_with_railway/chain_actions.py
from functools import reduce

def chain_actions[T](
    first: ActionSuccess[T], *rest: ActionSuccess[T]
) -> ChainRunner[T]:

    def thunk() -> ActionChain[T]:
        def reducer(chain: ActionChain[T], step: ActionSuccess[T]) -> ActionChain[T]:
            if chain.has_failed():
                return chain
            return (
                chain.then(step.__action__)
                .failure(step.__failure_handler__)
                .success(step.__success_handler__)
                .execute()
            )
        return reduce(reducer, rest, first.execute())

    return ChainRunner(thunk=thunk)

Anatomy#

FP concept	Python realization
Accumulator type	`ActionChain[T]`
Element type	`ActionSuccess[T]`
Reducer	`reducer(chain, step) -> ActionChain[T]`
Initial value	`first.execute()`
Iterable	`rest` (the `*rest` tuple)
Short-circuit	`if chain.has_failed(): return chain`
Result	`ActionChain[T]` (the last one)

Execution flow#

initial = first.execute()                                          # → ActionChain(ok=True, result=Ok(...))

step 1 : reducer(<initial>, act2) :
  chain.has_failed() = False
  chain.then(act2.__action__).failure(...).success(...).execute()
  → action raises → Fail
  → failure_handler(exc)  ❌ FIRE
  → ActionChain(ok=False, result=Fail(exc))

step 2 : reducer(<failed>, act3) :
  chain.has_failed() = True
  return chain                                                     ⚠️  short-circuit

result of the reduce = <failed ActionChain>

Why `reduce`#

# Imperative approach (equivalent)
def thunk() -> ActionChain[T]:
    chain = first.execute()
    for step in rest:
        if chain.has_failed():
            break
        chain = (
            chain.then(step.__action__)
            .failure(step.__failure_handler__)
            .success(step.__success_handler__)
            .execute()
        )
    return chain

Reduce	Imperative loop
A single value flows (the `chain`)	A state + a mutation
Reducer = pure function (testable in isolation)	Inline logic
Explicit “accumulator” semantics	Implicit logic
Functional standard	Imperative standard

An expression of intent: we fold a list onto an accumulator. Semantics jump out on the first read. This is what’s called a catamorphism.

04.04 — Static typing tests (pytest-mypy-plugins)

Wed, 20 May 2026 00:00:00 +0000

04.04 — Static typing tests (`pytest-mypy-plugins`)#

Five *test_types.yml files that test the checker’s behavior. A testing dimension unique to Ocarina in its way: we make sure that what should be a mypy error actually is one.

Listing#

tests/
├── dsl/
│   ├── invariants/test_types.yml
│   └── testing_with_railway/test_types.yml
└── opinionated/
    ├── cli/test_types.yml
    ├── infra/test_types.yml
    └── plugins/reports/...   (snapshots — not YAML)

YAML#

- case: compatible_predicate_types
  description: Predicates should accept values of compatible types
  main: |
    from ocarina.dsl.invariants.validate import validate
    from ocarina.dsl.invariants.assertions import is_email, is_positive

    validate(1234).assert_that(is_positive)
    validate("a@a.com").assert_that(is_email)

Without out: → we expect mypy to pass without error on the given code.

05.04 — Key UI components

Wed, 20 May 2026 00:00:00 +0000

05.04 — Key UI components#

The src/components/ files and their role in the playground.

Listing#

src/components/
├── BackToHome.tsx              # back-to-HOME button
├── BackToSicily.tsx            # variant
├── Button.tsx                  # Tailwind-styled button
├── ChaoticForm.tsx             # ⭐ form with .catch-me-if-you-can elements
├── Dropzone.tsx                # ⭐ react-dropzone wrapper for SACRED_UPLOAD
├── ErrorCode.tsx               # component showing an HTTP code (used by RANDOM_ERROR)
├── FakeUpload/                 # fake upload component (animation, no real POST)
├── InternalErrorMsg.tsx        # generic error message
├── Label.tsx                   # form label
├── Link.tsx                    # styled <a> wrapper
├── Loading.tsx                 # generic spinner
├── LoginForm.tsx               # ⭐ login form + MFA OTP
├── PlusButton.tsx              # + button (corsicamon: add to collection)
├── RandomBibleVerse.tsx        # random bible verse
├── RandomLoader.tsx            # ⭐ random loader
├── UploadPreview.tsx           # preview of an uploaded file
└── XButton.tsx                 # X close button

⭐ = key component for Ocarina scenarios.

06.04 — GET /api/corsicadex?id=N

Wed, 20 May 2026 00:00:00 +0000

06.04 — `GET /api/corsicadex?id=N`#

Source file: api/corsicadex.ts

Code#

import type { NextRequest } from "next/server";
import isAuthorized from "../lib/isAuthorized";
import { corsicaDexData } from "../consts/corsicadexData";

export const config = { runtime: "edge" };

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, OPTIONS",
  "Access-Control-Allow-Headers": "x-api-key, Content-Type",
} as const;

export default async function handler(request: NextRequest) {
  if (request.method === "OPTIONS") {
    return new Response(null, { status: 200, headers: corsHeaders });
  }

  if (!isAuthorized(request)) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { "Content-Type": "application/json", ...corsHeaders },
    });
  }

  const url = new URL(request.url);
  const id = url.searchParams.get("id");

  if (!id) {
    return new Response(JSON.stringify({ error: "Missing id parameter" }), {
      status: 400,
      headers: { "Content-Type": "application/json", ...corsHeaders },
    });
  }

  const corsicamonId = parseInt(id, 10);

  if (isNaN(corsicamonId)) {
    return new Response(JSON.stringify({ error: "Invalid ID" }), {
      status: 400,
      headers: { "Content-Type": "application/json", ...corsHeaders },
    });
  }

  const corsicamon = corsicaDexData.find((p) => p.id === corsicamonId);

  if (!corsicamon) {
    return new Response(JSON.stringify({ error: "Corsicamon not found" }), {
      status: 404,
      headers: { "Content-Type": "application/json", ...corsHeaders },
    });
  }

  return new Response(JSON.stringify(corsicamon), {
    headers: { "Content-Type": "application/json", ...corsHeaders },
  });
}

Mechanics#

Static lookup in a TypeScript array.

07.04 — Corsicamon scenarios

Wed, 20 May 2026 00:00:00 +0000

07.04 — Corsicamon scenarios#

Igoristan’s “Corsican Pokédex (Corsicadex)” page. API key input, random draw with 1/5 fail, transient_errors for Error('lol'), and POM-internal retries against “Corsicamons loaded / network error” states.

Campaign#

# src/tests/campaigns/corsicamon.py
def create_igoristan_corsicamon_campaign(*, drivers_pool) -> TestCampaign:
    return TestCampaign(
        name="Corsicamon",
        suites=[
            create_corsicamon_happy_paths_test_suite(drivers_pool=drivers_pool),
            create_corsicamon_unhappy_paths_test_suite(drivers_pool=drivers_pool),
        ],
    )


def create_igoristan_corsicamon_smoke_campaign(*, drivers_pool) -> TestCampaign:
    return TestCampaign(
        name="Corsicamon - Smoke",
        suites=[create_corsicamon_smoke_tests_suite(drivers_pool=drivers_pool)],
    )

Smoke test#

# tests/scenarios/corsicamon/enter_api_key.py
def scenario_enter_api_key_smoke(driver, logger):
    page = CorsicamonEnterApiKeyPage(driver=driver)
    ...
    return [
        drive_page(
            act(page, open_corsicamon_page)...,
            act(page, verify_enter_api_key_screen)...,
        ),
    ]


test_enter_api_key_smoke = create_selenium_test(
    name="Corsicamon - Smoke - enter API key screen visible",
    test_scenario=lambda driver, logger: Scenario(
        test_chain=scenario_enter_api_key_smoke(driver, logger)
    ),
)

Verifies the API key entry page appears. Fails → smoke fails → main campaigns skipped.

08.04 — Test strategy

Wed, 20 May 2026 00:00:00 +0000

08.04 — Test strategy#

Six test types, six distinct roles. Documented in CURA_TEST_STRATEGY.md §3.

Test types#

Type	Expected status	Authoritative source
Happy path	PASS	Nominal flows described from the FRDs
Unhappy path	PASS (the test passes when the app correctly refuses)	Existing validations work
Edge case / boundary	PASS or FAIL	Depending on the test, often accompanied by a note added to the FRDs
Business logic vulnerability / gap test (functional tests trying to “break” the product and identify gaps)	Intentional FAIL	Behaviors a system should prevent but CURA doesn’t
Exploratory / observed-behaviour	PASS	Documents current behavior when the spec doesn’t cover it
Permanent security regression fixture	PASS (= security holds)	Verifies a security fix holds (fixes that stay permanently in the test heritage)

Happy path#

Exercises the nominal flow with valid inputs and an authenticated user. Verifies that the system produces the correct output (confirmation, history entry, etc.).

09.03.04 — Comprehend skills

Wed, 20 May 2026 00:00:00 +0000

09.03.04 — Comprehend skills#

Skills that help the AI understand a project or ecosystem before acting.

Listing (potentially non-exhaustive)#

Skill	Target
`assess-test-base`	Catalogs the existing test base
`assess-ecosystem`	Bounded public research, capped by a token budget
`assess-impact`	Forward impact analysis: a change’s blast radius through the dependency graph
`understand-sut-constraints`	Understands the SUT’s “boundaries” so as not to exceed them
`understand-ocarina`	Routes by question class: Holy Book for reference, the from-ocarina-to-igor book for intent; then Ocarina source + the adapter-matched worked example

`understand-ocarina`#

input  : user question — routed by class:
            - "how do I do a match_page?"        (reference: what a primitive is) → Holy Book
            - "why is the suite built on Railway?" (intent / cartography / why)    → the from-ocarina-to-igor book
output : Claude loads, by question class:
            - reference  → relevant Holy Book pages (https://mojo-molotov.github.io/ocarina-holy-book)
            - intent     → relevant chapters of the from-ocarina-to-igor book (https://mojo-molotov.github.io/from-ocarina-to-igor/)
            - behaviour  → Ocarina source clone, if the docs don't cover it
            - shape      → the worked example matching the project's driver adapter:
                              Selenium   → ocarina-example, ocarina-with-ai-example
                              Playwright → ocarina-with-playwright-example
         then answers with citations (tier + page/chapter URL or file:line)

SKILL.md:

09.04 — CLAUDE.md and CLAUDE.slim.md

Wed, 20 May 2026 00:00:00 +0000

09.04 — `CLAUDE.md` and `CLAUDE.slim.md`#

The Holy Book actively publishes the CLAUDE.md files. This lets an LLM fetch the project’s docs without going through the repo.

The two files#

ai/
├── CLAUDE.md       # full version (rules + project layout)
└── CLAUDE.slim.md  # short version (rules only)

Public URLs#

https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.md
https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.slim.md

Holy Book quote (chapter “Using Ocarina with AI”):

Slim when context is heavy; full for onboarding and reviews. Full wins on disagreement.

10.04 — ocarina-with-ai-example workflows

Wed, 20 May 2026 00:00:00 +0000

10.04 — `ocarina-with-ai-example` workflows#

See also ../08-ai-example/09-ci-matrix.md

Overview#

Workflow	Trigger	OS	Effect	Note
`ai_proof_ci.yml`	push main, PR, dispatch	ubuntu × py 3.14	`ruff format src/ --check` + `ruff check src/` + `mypy src/`	PR gate, fast
`ai_proof_e2e.yml`	dispatch	ubuntu × firefox+chrome matrix	Heroku warm-up + run + sed filter ChromeDriver C++ stacks + upload	Manual only

Differences vs `ocarina-example`#

Aspect	`ocarina-example`	`ocarina-with-ai-example`
Browser matrix	Firefox only (e2e.yml)	Firefox + Chrome (parallelized)
SUT	Igoristan (GitHub Pages)	CURA (Heroku eco-dyno)
Pre-run	warm-up Redis client	warm-up Heroku dyno
Output filter	none	sed filters ChromeDriver C++ stack frames
`WAIT_TIMEOUT`	default 10	15 (compensates for Heroku latency)

Heroku warm-up#

curl -sf --retry 6 --retry-delay 5 --retry-all-errors \
  --max-time 30 https://katalon-demo-cura.herokuapp.com/ > /dev/null
echo "Dyno is warm"

CURA runs on a Heroku dyno that sleeps after inactivity. Tests hitting a cold dyno produce timeouts (false fails) and slow confirmations (false passes on gap tests). Wake it explicitly before any browser opens.

12.04 — Zone-H, IRC, EFnet

Wed, 20 May 2026 00:00:00 +0000

12.04 — Zone-H, IRC, EFnet#

Three infrastructures without which the 1998-2012 hacker scene would never have been the same: Zone-H (deface archive), IRC, EFnet (the historical IRC network). The Holy Book cites Zone-H only once, but it’s a keyword that opens an entire infrastructure.

1. Zone-H — deface archive (2002 → today)#

Foundation#

Date: March 2, 2002.
HQ: Estonia.
Founder: Roberto Preatoni (alias Sys64738).
URL: zone-h.org

Function#

An attacker defaces a site (replaces the homepage with their own version, signed).
The attacker (or a witness) submits the URL to Zone-H.
Zone-H moderates: verifies the deface is authentic.
If OK: the defaced site is archived forever on Zone-H (HTML+CSS+assets snapshot).
The deface author signs with their alias. Sourcing is public.

Impact#

For 10-15 years, Zone-H was the public scoreboard of the global grey hat scene. Every notable deface was archived. For a script kiddie, climbing the Zone-H rankings was the goal to prove:

01.05 — The project's political stance

Wed, 20 May 2026 00:00:00 +0000

01.05 — The project’s political stance#

The Holy Book doesn’t separate philosophy from the politics of the repo itself. Five operating commitments come out of it.

1. Incorruptibility#

Sharing Ocarina means sharing a car I have maintained entirely myself, for myself, therefore with great care. Still, it is shared as-is, and will remain so. It’s my car.

I channeled all my anger into it, to pour all my love into it.

02.03.05 — create_act and its hooks

Wed, 20 May 2026 00:00:00 +0000

02.03.05 — `create_act` and its hooks#

Source file: src/ocarina/dsl/testing_with_railway/constructors/create_act.py

The low-level primitive that builds a test step constructor. You call it once to mint a project-specific act verb. In theory a complex project might want several distinct act verbs with different hooks, but no real-world need has shown up yet — recommendation: create one. Not a singleton, just a convention.

Signature#

def create_act(
    pom: TPOM,
    action: Callable[[TPOM], TPOM],
    *,
    on_failure: Callable[[TPOM, Exception], Fail] | None = None,
    on_run_effect: Effect | None = None,
    act_counter_effect: Effect | None = None,
) -> ActionStart[TPOM]:

Parameter	Position	Type	Role
`pom`	positional	`TPOM` (bound `POMBase`)	The page (or any `POMBase` subclass) you’re acting on.
`action`	positional	`Callable[[TPOM], TPOM]`	The function that acts on the page and returns the page (fluent). Identity-typed.
`on_failure`	keyword-only	`Callable[[TPOM, Exception], Fail] \| None`	Hook for refining the `Fail`: if you reach this, you’ve already failed; the hook just lets you type the error more precisely (e.g. `HttpErrorPageReachedError`).
`on_run_effect`	keyword-only	`Effect \| None`	Side effect called before the action (e.g.: log a step number).
`act_counter_effect`	keyword-only	`Effect \| None`	Additional side effect called before the action. Default: increments the act counter.

Code#

def run_action() -> Result[TPOM]:
    try:
        if act_counter_effect:
            act_counter_effect()
        else:
            ThreadsBasedActCounter().incr_act_call_count()

        if on_run_effect:
            on_run_effect()

        result_pom = action(pom)
        return Ok(result_pom)
    except Exception as exc:  # noqa: BLE001
        if on_failure:
            return on_failure(pom, exc)
        return Fail(error=exc)

return ActionStart(run_action)

The try wraps EVERYTHING: act_counter_effect, on_run_effect, and the action. If any side effect raises (say on_run_effect hits a dead resource), it counts as a test-step failure. Everything that runs “during the test step” IS the test step.
Order is deterministic: counter → run effect → action. The counter ticks even if the action ends up failing. Intentional — we want to know how many steps were attempted, not how many passed.
on_failure can return an enriched Fail: that’s where a WebDriverException becomes an HttpErrorPageReachedError.

Default `ActCounter`: `ThreadsBasedActCounter`#

from ocarina.opinionated.infra.act_counter import ActCounter as ThreadsBasedActCounter
# ...
if act_counter_effect:
    act_counter_effect()
else:
    ThreadsBasedActCounter().incr_act_call_count()

Source: src/ocarina/opinionated/infra/act_counter.py

02.04.05 — BusinessInvariantValidator vs FrameworkInvariantValidator

Wed, 20 May 2026 00:00:00 +0000

02.04.05 — `BusinessInvariantValidator` vs `FrameworkInvariantValidator`#

Two factories, identical code, exist purely to signal intent.

Code#

class _BaseCustomInvariantValidator:
    @staticmethod
    def create[T](
        value: T,
        name: str,
        build_chain: Callable[[ValidationStartBlock[T], T], ValidationAssertBlock[T]],
    ) -> ValidationAssertBlock[T]:
        return _create_business_invariant_validator(
            value, name, lambda chain: build_chain(chain, value)
        )


@final
class BusinessInvariantValidator(_BaseCustomInvariantValidator):
    """Factory for creating business domain invariant validators.

    Use this for domain-specific validation logic (e.g., "user must be adult",
    "order total must match items").
    """


@final
class FrameworkInvariantValidator(_BaseCustomInvariantValidator):
    """Factory for creating framework-level invariant validators.

    Use this for technical/framework validation logic (e.g., "config must be valid",
    "test structure must be correct").
    """

def _create_business_invariant_validator[T](
    value: T,
    name: str,
    build_chain: ValidationChainBuilder[T],
) -> ValidationAssertBlock[T]:
    start_block = validate(value, name=name)
    return build_chain(start_block)

Why two classes?#

BusinessInvariantValidator flags a business rule; FrameworkInvariantValidator, a technical framework rule. Intent jumps off the page.
Grep. FrameworkInvariantValidator.create finds every framework invariant in one search. Same for business rules on the project side.
Maintainability. Want to add behavior (different log, different stack trace) to one or the other? Do it without touching every call-site.

Usage#

Invariant	Category	Where it lives
`validate_workers_amount`	Framework	`src/ocarina/custom_invariants/testing/workers.py`
`validate_test_runners_ids`	Framework	`src/ocarina/custom_invariants/testing/oc_test_runners_ids.py`
`validate_test_runners_names`	Framework	`src/ocarina/custom_invariants/testing/oc_test_runners_names.py`
`validate_test_suites_names`	Framework	`src/ocarina/custom_invariants/testing/oc_test_suites_names.py`
`validate_test_campaigns_names`	Framework	`src/ocarina/custom_invariants/testing/oc_test_campaigns_names.py`
`validate_test_cycle_name`	Framework	`src/ocarina/custom_invariants/testing/oc_test_cycles_names.py`
Business example: “the username must be on the whitelist”	Business	To be written on the user project side
Business example: “the booking date must be future and < 1 year”	Business	To be written on the user project side

Full pattern#

# src/ocarina/custom_invariants/testing/workers.py
from ocarina.dsl.invariants.assertions import is_not_zero, is_positive
from ocarina.dsl.invariants.validate import FrameworkInvariantValidator


def _workers_amount_chain(
    chain: ValidationStartBlock[int],
    value: int,
) -> ValidationAssertBlock[int]:
    msg = f"Value Error: Number of workers must be at least 1 (got: {value})."
    return chain.assert_that(is_positive, msg=msg).assert_that(is_not_zero, msg=msg)


def validate_workers_amount(
    *, workers_amount: int, name: str
) -> ValidationAssertBlock[int]:
    """Validate that workers amount is at least 1."""
    return FrameworkInvariantValidator.create(
        workers_amount, name, _workers_amount_chain
    )

Private _workers_amount_chain(chain, value) -> ValidationAssertBlock defines the what.
Public validate_workers_amount(*, workers_amount, name) is the API and delegates to FrameworkInvariantValidator.create.
Caller in TestSuite.run: validate_workers_amount(...).execute().raise_if_invalid().

Which factory for which case#

Holy Book (excerpt from the “Extensibility” chapter):

02.05.05 — Worker saturation

Wed, 20 May 2026 00:00:00 +0000

02.05.05 — Worker saturation#

Ocarina-specific trick: if a suite has fewer tests than workers, tests get randomly cloned until the worker count is filled. Copies are renamed [COPY 1] <name>, [COPY 2] <name>, etc.

Why#

The Holy Book formalizes the rationale in the “First real-world hurdles” chapter:

Its saturate_workers option lets you force random cloning of tests inside a suite.

As soon as there are more available workers in the DriversPool than there are tests to run in a suite, Ocarina will randomly clone tests, start every driver, and assign each one a test to perform.

02.10.05 — Selenium adapters

Wed, 20 May 2026 00:00:00 +0000

02.10.05 — Selenium adapters#

Source folder: src/ocarina/infra/selenium/

Everything that materializes the abstractions (POMBase, WebDriversPool, Screenshotter) in Selenium flavor. Lives outside the pure DSL — and since 1.1.3 it has a twin: src/ocarina/infra/playwright/ ships the exact same contracts in Playwright flavor. Swapping backend is now picking a folder, not writing one.

Files in the folder#

File	Role
`create_driver.py`	`_build_firefox`, `_build_chrome`, `_build_edge`, `_build_safari` + dispatch
`create_drivers_pool.py`	`create_selenium_drivers_pool` (uses `DriverBuilder` + `WebDriversPool`)
`create_screenshotter.py`	`create_selenium_screenshotter` + `_selenium_save_full_page` (Firefox-only)
`driver_healthcheck.py`	`driver_healthcheck(driver)` — pings `driver.title`
`mixins.py`	`SeleniumTitleMixin`

`create_driver.py`#

def _build_firefox(*, profile_path, driver_path, headless, wait_timeout) -> WebDriver:
    service = FirefoxService(executable_path=driver_path)
    options = FirefoxOptions()
    if headless:
        options.add_argument("-headless")
    if profile_path:
        options.profile = FirefoxProfile(profile_path)
    driver = Firefox(service=service, options=options)
    driver.implicitly_wait(wait_timeout)
    return driver


def _build_chrome(*, profile_path, driver_path, headless, wait_timeout) -> WebDriver:
    service = ChromeService(executable_path=driver_path)
    options = ChromeOptions()
    if headless:
        options.add_argument("--headless=new")
    if profile_path:
        options.add_argument(f"--user-data-dir={profile_path}")
    driver = Chrome(service=service, options=options)
    driver.implicitly_wait(wait_timeout)
    return driver


def _build_edge(*, profile_path, driver_path, headless, wait_timeout) -> WebDriver:
    # … same as Chrome with EdgeService/EdgeOptions/Edge …


def _build_safari(*, profile_path, driver_path, headless, wait_timeout) -> WebDriver:
    # … Safari supports neither driver_path (uses macOS' native safaridriver),
    #   nor profile_path (no custom profile), nor headless …

1. `implicitly_wait` set only once#

Each builder calls driver.implicitly_wait(wait_timeout) once. Any find_element that doesn’t find the element immediately waits up to wait_timeout seconds before raising NoSuchElementException.

02.11.05 — Report plugins

Wed, 20 May 2026 00:00:00 +0000

02.11.05 — Report plugins#

Source folder: src/ocarina/opinionated/plugins/reports/

pretty_print_results, results_to_json, generate_docx_proof, timing. All opt-in. Run sequentially or in parallel via run_plugins.

`pretty_print_results`#

# src/ocarina/opinionated/plugins/reports/pretty_print_results.py
def pretty_print_results(results: TestCycleResults, *, with_colors: bool = False) -> None:
    """Display the full test results."""

Campaign
• Suite
  > Test case 1
    » PASSED
  > Test case 2
    » FAILED
      → Error message
        ⫸ At step 3
  > Test case 3
    » SKIPPED

Test results:
1 FAILED | 1 PASSED | 1 SKIPPED

Aspect	Detail
Hierarchy	3 levels: campaign `•`, suite `>`, case `»`
Levels	`PASSED` (green), `FAILED` (red), `SKIPPED` (gray)
Error	Message + step number where it failed ("At step 3")
Summary	Aggregated count at the bottom

`results_to_json`#

def generate_json_results(*, results: TestCycleResults, output_dir: Path, logger: ILogger) -> None:
    """Write test results to a JSON file in results_dir."""
    output_dir.mkdir(parents=True, exist_ok=True)
    max_stem_length = 8
    max_attempts = 500
    for _ in range(max_attempts):
        filename = f"{uuid.uuid4().hex[:max_stem_length]}.json"
        file_path = output_dir / filename
        if not file_path.exists():
            break
    else:
        raise RuntimeError(f"Can't generate unique JSON filename in: {output_dir}.")

{
  "Campaign": {
    "Suite": {
      "test_case": [
        {"status": "success" | "fail", "error": "..."},
        counter,
        metadata
      ]
    }
  }
}

def _result_to_serializable(v: Any) -> dict[str, str]:
    if is_ok(v):
        return {"status": "success"}
    if is_fail(v):
        return {"status": "fail", "error": str(v.error)}
    raise TypeError(f"Expected Ok or Fail instances, but got: {type(v)}")

Filename is an 8-char hex UUID → 16⁸ ≈ 4 billion options. No collisions in practice. 500 safety retries.

03.05 — Declarative programming

Wed, 20 May 2026 00:00:00 +0000

03.05 — Declarative programming#

An Ocarina scenario describes, it doesn’t execute. That’s what makes it factorable, multipliable, readable.

Demonstration#

return [
    drive_page(
        act(on_homepage, open_then_verify_homepage)
            .failure(just_log_error("Failed to reach the homepage..."))
            .success(log_success_with_current_url_and_take_screenshot("On the homepage!")),
        act(on_homepage, click_book_call_page_cta)
            .failure(just_log_error("Failed to click on the 'Book a call' CTA..."))
            .success(just_log_success("Clicked on the 'Book a call' CTA!")),
    ),
    drive_page(
        act(on_book_a_call_page, verify_book_call_page)
            .failure(just_log_error("Failed to verify the 'Book a call' page..."))
            .success(log_success_with_current_url_and_take_screenshot("On the 'Book a call' page!")),
    ),
]

This code executes nothing. It describes:

04.05 — Snapshot testing (syrupy)

Wed, 20 May 2026 00:00:00 +0000

04.05 — Snapshot testing (`syrupy`)#

syrupy is a pytest plugin that serializes a test’s output into a .ambr file and compares to subsequent runs. Used for the output of pretty_print_results and results_to_json.

`.ambr`#

tests/opinionated/plugins/reports/__snapshots__/
├── test_pretty_print_results.ambr
└── test_results_to_json.ambr

Generated and managed by syrupy.

Example#

# tests/opinionated/plugins/reports/test_pretty_print_results.py
def test_pretty_print_results_renders_campaign_suite_test(snapshot, capsys):
    results = {
        "Dashboard": {
            "Login happy paths": {
                "Login - without OTP": (Ok(None), 5, "login_no_otp"),
                "Login - with OTP": (Fail(error=RuntimeError("OTP missed")), 8, "login_otp"),
                "Skipped one": (None, -1, "skipped_one"),
            },
        },
    }
    pretty_print_results(results, with_colors=False)
    out = capsys.readouterr().out
    assert out == snapshot

The snapshot (syrupy fixture):

05.05 — wireit pipelines

Wed, 20 May 2026 00:00:00 +0000

05.05 — `wireit` pipelines#

wireit is an NPM script orchestrator with incremental cache. Igoristan uses it to chain format-check, lint, typecheck, prebuild, build, dev, preview, all with fine per-task caching.

`package.json#wireit`#

"wireit": {
  "ci:format-check": {
    "command": "prettier . --check",
    "files": ["*.{js,ts,jsx,tsx,json,md,mdx,html,css,scss,yml,yaml}"],
    "output": []
  },
  "clean:dist": {
    "command": "rimraf dist",
    "files": ["dist/"],
    "output": []
  },
  "prebuild": {
    "files": ["src/**/*.*", "package.json", "packages/**/*.*", "packages/**/package.json", "vite.config.ts"],
    "dependencies": ["lint", "typecheck"]
  },
  "preview": {
    "command": "vike preview",
    "dependencies": ["build"]
  },
  "dev": {
    "command": "vike dev",
    "files": ["src/**/*.*", "packages/**/*.*"],
    "dependencies": ["prebuild"],
    "output": ["dist/"],
    "packageLocks": ["pnpm-lock.yaml"]
  },
  "build": {
    "command": "vike build",
    "files": ["src/**/*.*", "packages/**/*.*"],
    "dependencies": ["prebuild"],
    "output": ["dist/"],
    "packageLocks": ["pnpm-lock.yaml"]
  },
  "lint": {
    "command": "eslint \"./{src,packages}/**/*.{js,jsx,ts,tsx}\" --max-warnings 0 --cache",
    "files": ["src/**/*.*", "package.json", "packages/**/*.*", "eslint.config.ts"],
    "output": []
  },
  "typecheck": {
    "command": "tsc --build --pretty tsconfig.json",
    "files": ["src/**/*.*", "package.json", "tsconfig.app.json", "tsconfig.json", "tsconfig.node.json"],
    "output": ["typecheck-dist/"]
  }
}

DAG#

                 ┌─────────────────┐
                 │ ci:format-check │ ────► prettier . --check
                 └─────────────────┘
                 ┌─────────────────┐
                 │     lint        │ ────► eslint (max-warnings 0, --cache)
                 └─────┬───────────┘
                       │
                 ┌─────▼───────────┐
                 │   typecheck     │ ────► tsc --build --pretty
                 └─────┬───────────┘
                       │
                 ┌─────▼───────────┐
                 │   prebuild      │ ────► deps: [lint, typecheck]
                 └─────┬───────────┘
                       │
            ┌──────────┴──────────┐
            ▼                     ▼
   ┌─────────────────┐    ┌─────────────────┐
   │   build         │    │   dev           │
   │   vike build    │    │   vike dev      │
   └────┬────────────┘    └─────────────────┘
        ▼
   ┌─────────────────┐
   │   preview       │
   │   vike preview  │
   └─────────────────┘

With pnpm dev:

06.05 — isAuthorized.ts

Wed, 20 May 2026 00:00:00 +0000

06.05 — `isAuthorized.ts`#

Source file: lib/isAuthorized.ts

Verifies that a request contains the right x-api-key.

Code#

import type { NextRequest } from "next/server";

const API_SECRET = process.env.API_SECRET;

function isAuthorized(request: NextRequest): boolean {
  if (typeof API_SECRET !== "string") {
    console.error("[CONFIG ERROR] API_SECRET is not defined");
    return false;
  }

  const { searchParams } = new URL(request.url);
  const apiKey = searchParams.get("apiKey") ?? request.headers.get("x-api-key");
  return apiKey === API_SECRET;
}

export default isAuthorized;

Approach#

1. `API_SECRET`#

const API_SECRET = process.env.API_SECRET;

Read once at Edge worker startup (cold start), stored as a module variable. Faster than hitting process.env on every call.

07.05 — Randomness scenarios (4 levels)

Wed, 20 May 2026 00:00:00 +0000

07.05 — Randomness scenarios (4 levels)#

Four progressive levels of chaos. We start simple, ramp up complexity, stress Ocarina more and more.

Campaign#

# src/tests/campaigns/randomness.py
def create_igoristan_randomness_campaign(*, drivers_pool) -> TestCampaign:
    return TestCampaign(
        name="Randomness",
        suites=[create_randomness_test_suite(drivers_pool=drivers_pool)],
    )

Suite#

# src/tests/suites/randomness.py
def create_randomness_test_suite(*, drivers_pool) -> TestSuite:
    return TestSuite(
        name="Randomness",
        tests=[
            test_random_error_page,                     # level 1
            test_random_loaders_page,                   # level 1
            test_dsed,                                  # level 2
            test_madness,                               # level 2
            test_chaotic_form,                          # level 3
            test_walkthrough,                           # level 4
        ],
        drivers_pool=drivers_pool,
    )

Levels#

Level	Mechanic exercised	Difficulty
1	Base DSL (`drive_page`, `act`)	easy
2	`match_page` / `when`	medium
3	`HumanizedDriver` + `Watcher`	hard
4	Multi-page chaotic walkthrough	hard

Level 1 — Random Error Page#

# tests/scenarios/randomness/level_1/random_error_page.py
def scenario_random_error_page(driver, logger):
    page = RandomErrorPage(driver=driver)
    return [
        drive_page(
            act(page, open_random_error_page)...,
            act(page, verify_random_error_page)...,
        ),
    ]


test_random_error_page = create_selenium_test(
    name="Random Error Page - smoke",
    test_scenario=lambda driver, logger: Scenario(test_chain=scenario_random_error_page(driver, logger)),
)

Deliberately flaky — exercises the on_failure hook.

08.05 — Security gaps (G-SEC-1 to G-SEC-3)

Wed, 20 May 2026 00:00:00 +0000

08.05 — Security gaps (G-SEC-1 to G-SEC-3)#

Three documented security gaps. Not actively exploited (cf. the rule “security testing is functional and static, never active”), but observed via functional tests.

G-SEC-1 — No CSRF token on the front-end forms#

Symptom#

The <form> rendered on Heroku does not contain a CSRF token.

Source#

views/page_appointment.php in the GitHub repo calls $antiCSRF->insertHiddenToken() before the submit button. But on the deployed version, this token does not appear in the HTML.

09.03.05 — Pick skills

Wed, 20 May 2026 00:00:00 +0000

09.03.05 — Pick skills#

Picking artifacts (screenshots, logs, reports). Always by mtime, never by filename.

Listing (potentially non-exhaustive)#

Skill	Target
`pick-screenshots`	Picks the most recent screenshots (by mtime), contextualizing them with logs where possible
`pick-logs`	Picks the most recent logs (by mtime)
`pick-reports`	Picks the most recent DOCX/JSON reports (by mtime)

“mtime”#

Holy Book quote:

Mtime, not filename. UUID suffixes are random; pick-* sorts by mtime.

09.05 — PDF generation (generate-books)

Wed, 20 May 2026 00:00:00 +0000

09.05 — PDF generation (`generate-books`)#

The public PDFs (ocarina-ru.pdf, ocarina-en.pdf, ocarina-fr.pdf…) are AI-generated from the docs/ folder, a Python script, and a Markdown prompt.

Tree#

prompts/generate-books/
├── prompt.md                     # spec (read by the AI)
├── script.py                     # Python implementation
├── NotoSans-Regular.ttf
├── NotoSans-Bold.ttf
├── NotoSans-Italic.ttf
├── NotoSans-BoldItalic.ttf
├── NotoSansMath-Regular.ttf
├── NotoSansMono-Regular.ttf
├── NotoSansSymbols2-Regular.ttf
├── NotoNaskhArabic-Regular.ttf
└── NotoColorEmoji-Regular.ttf

1. A `prompt.md` + a `script.py`#

prompt.md:

Ocarina PDF Generator#

What this is#

A system that turns a VitePress docs/ folder (Markdown + images) into three polished A4 PDFs — one Russian, one English, one French. The system is two files: this prompt (the spec) and script.py (the implementation). They are designed to be used together in an agentic environment.

10.05 — igoristan workflows

Wed, 20 May 2026 00:00:00 +0000

10.05 — `igoristan` workflows#

See also ../05-igoristan/07-ci-deploy.md

Overview#

Workflow	Trigger	OS	Effect	Note
`ci-pr.yml`	PR `**`, dispatch	ubuntu × node 24 + pnpm 10	3 parallelized jobs: `wireit ci:format-check` + `wireit lint` + `wireit typecheck`	PR gate
`deploy.yml`	push main, dispatch	ubuntu × node 24 + pnpm 10	`pnpm install --frozen-lockfile` + `pnpm build` + upload Pages	Production

`ci-pr.yml`#

jobs:
  format-check:
    env:
      WIREIT_CACHE: github
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v5
        with: { version: 11 }
      - uses: actions/setup-node@v6
        with: { node-version: 24, cache: "pnpm" }
      - uses: google/wireit@setup-github-actions-caching/v2
      - run: make install
      - name: Formatcheck
        run: make ci:format-check

  lint:
    env:
      WIREIT_CACHE: github
    steps:
      # ... same setup ...
      - uses: actions/cache@v5
        with:
          path: .eslintcache
          key: eslint-cache-${{ hashFiles('eslint.config.ts', 'src/**/*.*', 'package.json') }}
      - name: Lint
        run: pnpm lint

  typecheck:
    env:
      WIREIT_CACHE: github
    steps:
      # ... same setup ...
      - name: Typecheck
        run: pnpm typecheck

Job	Additional cache
`format-check`	wireit
`lint`	wireit + `.eslintcache` (actions/cache)
`typecheck`	wireit + `tsbuildinfo` (via wireit)

`WIREIT_CACHE: github`#

env:
  WIREIT_CACHE: github
steps:
  - uses: google/wireit@setup-github-actions-caching/v2

Enables the wireit cache. Subsequent runs reuse wireit artifacts.

12.05 — Early-2000s Indonesian hackers

Wed, 20 May 2026 00:00:00 +0000

12.05 — Early-2000s Indonesian hackers#

The Holy Book quotes “the first Indonesian hacker group” without naming it in the main text, but the cited mantra ("We Can Do All What You Can’t Do") is indeed YogyaCarderLink (YCL)’s. It remains to explain why the Indonesian scene of that era deserves a citation in a 2026 testing framework manifesto.

1. The May 1998 riots#

The trigger#

In May 1998, Indonesia went through a major economic crisis (fallout from the 1997 Asian crisis) and a political crisis (end of the Suharto regime). Riots broke out in Jakarta, Medan, Surakarta, notably targeting the Indonesian Chinese minority (merchants, middle class). Estimates: ~1000 dead, hundreds of documented rapes.

02.10.06 — The Playwright actor: one owner thread

Mon, 01 Jun 2026 00:00:00 +0000

02.10.06 — The Playwright actor: one owner thread#

Source folder: src/ocarina/infra/playwright/

The Playwright adapter mirrors the Selenium one file for file (create_driver, create_drivers_pool, create_screenshotter, driver_healthcheck, mixins), with one extra file: driver.py. That file deserves a chapter of its own. It is what reconciles Playwright’s sync API — inherently bound to one thread — with Ocarina’s threaded model (pool, warmup, Watcher). The model has been stressed and stabilized; it holds.

The problem: Playwright’s sync API is thread-affine#

Playwright’s sync API binds every object it hands out — Playwright, Browser, BrowserContext, Page, Locator, … — to the thread that called sync_playwright().start(). Under the hood it is a greenlet pinned to that thread. Touching any of them from another thread raises:

02.03.06 — drive_page

Wed, 20 May 2026 00:00:00 +0000

02.03.06 — `drive_page`#

Source file: src/ocarina/opinionated/dsl/drive_page.py

Code#

def drive_page(
    first: ActionSuccess[TPOM], *rest: ActionSuccess[TPOM]
) -> ChainRunner[TPOM]:
    return chain_actions(first, *rest)

Literally chain_actions.

Why this alias?#

1. Semantics: “I’m taking control of a page”#

Holy Book quote (“First scenarios”):

drive_page expresses the fact that you are taking control of one page. Any transition becomes explicit through the opening of a new drive_page.

return [
    drive_page(
        act(on_homepage, open_homepage)...,
        act(on_homepage, verify_homepage)...,
        act(on_homepage, click_cta)...,
    ),                                          # ⬅ closing control of the homepage
    drive_page(                                 # ⬅ opening control of the next page
        act(on_target_page, verify_target_page)...,
    ),
]

2. Discipline#

Mixing acts from two different POMs inside one drive_page is a mypy error (see 02-action-chain-states.md, “narrowing via act()” section). The semantics get enforced concretely.

02.04.06 — Invariant error hierarchy

Wed, 20 May 2026 00:00:00 +0000

02.04.06 — Invariant error hierarchy#

Source file: src/ocarina/dsl/invariants/errors.py

InvariantViolationError (base — subclass of Exception)
├── DuplicatesError                  (raised by `has_unique_elements`)
└── AggregateInvariantViolationError (raised by `_ValidationResult.raise_if_invalid`)

`InvariantViolationError`#

class InvariantViolationError(Exception):
    """Base exception raised when an invariant is violated."""

Bare Exception subclass, no extra logic. Every predicate raises this (or a subclass).

try:
    validate(value).assert_that(predicate).execute().raise_if_invalid()
except InvariantViolationError as e:
    logger.error(f"Validation failed: {e}")

… catches every violation with a single clause.

`DuplicatesError`#

class DuplicatesError(InvariantViolationError):
    def __init__(self, duplicates: Sequence[Any], message: str | None = None) -> None:
        self.duplicates = duplicates
        msg = message or "Duplicate elements detected:\n" + "\n".join(
            f" - {d}" for d in duplicates
        )
        super().__init__(msg)

Stashes the duplicate list in .duplicates.
Default message: “Duplicate elements detected:\n - apple\n - banana”.
Accepts a custom message=.

Raised by has_unique_elements.

02.05.06 — TestCampaign[Driver]

Wed, 20 May 2026 00:00:00 +0000

02.05.06 — `TestCampaign[Driver]`#

Source file: src/ocarina/dsl/testing/oc_test_campaign.py

One job: run a sequence of suites in order, share a workers config, and declare campaign_has_failed.

Code#

class TestCampaign[Driver]:
    def __init__(
        self,
        *,
        name: str,
        suites: Sequence[TestSuite[Driver]],
        max_workers: int,
        saturate_workers: bool | None = None,
    ) -> None:
        validate_test_suites_names(suites=suites, name="suites").execute().raise_if_invalid()

        self.name = name
        self._suites = suites
        self._results: TestCampaignResults = {}
        self._max_workers = max_workers
        self._saturate_workers = saturate_workers

        for suite in self._suites:
            suite._campaign_name = self.name

    def run_all(
        self, *, skip_all: bool = False, saturate_workers: bool = True
    ) -> TestCampaignResults:
        self._results.clear()

        resolved_saturate_workers = (
            self._saturate_workers
            if self._saturate_workers is not None
            else saturate_workers
        )

        if skip_all:
            for suite in self._suites:
                self._results[suite.name] = {
                    name: (None, -1, test_id)
                    for name, test_id in suite.test_names_and_ids
                }
            return self._results

        for suite in self._suites:
            self._results[suite.name] = suite.run(
                max_workers=self._max_workers,
                saturate_workers=resolved_saturate_workers,
            )

        return self._results


def campaign_has_failed(results: TestCampaignResults) -> bool:
    return any(
        is_test_result_fail(outcome)
        for campaign_results in results.values()
        for outcome, _, _ in campaign_results.values()
    )

Anatomy#

Constructor guard#

validate_test_suites_names(suites=suites, name="suites").execute().raise_if_invalid()

→ Suite names inside a campaign must be unique — case-insensitively since 1.1.10 (NFC + casefold). Raised at construction.

02.06 — Scenario[Driver]

Wed, 20 May 2026 00:00:00 +0000

02.06 — `Scenario[Driver]`#

Source file: src/ocarina/custom_types/scenario.py

Dataclass#

@final
@dataclass(frozen=True)
class Scenario[Driver]:
    test_chain: TestChain
    setup: TestSetup = field(default=None)
    teardown: TestTeardown = field(default=None)
    watchers: TestWatchers[Driver] | None = field(default=None)

# src/ocarina/custom_types/test_components.py
type TestChain = Sequence[ChainRunner[Any]]
type TestSetup = Effect | None
type TestTeardown = Effect | None
type TestWatchers[Driver] = Sequence[Watcher[Driver]] | None

Lifecycle (per attempt)#

1. setup()           — optional, free-form Effect (DB, API, …)
       → raises    :  test_chain skipped, jump to teardown,
                      return Outcome(setup_failed=True, should_retry=True)
       → ok        :  continue to test_chain

2. test_chain        — the actual chain (Sequence[ChainRunner])
       (watchers run during this time)

3. teardown()        — optional, always executed
       → raises    :  log warning + ignore (does not affect the verdict)

If EVERY attempt raises during setup:
    → test marked SKIPPED (not FAILED)
    → warning log « setup keeps failing »

`setup` and `teardown`#

setup and teardown are driver-free and injection-free by design.

02.11.06 — bootstrap + run_plugins

Wed, 20 May 2026 00:00:00 +0000

02.11.06 — `bootstrap` + `run_plugins`#

Source file: src/ocarina/opinionated/launcher/bootstrap.py

Entry point of an Ocarina project.
Three steps: cycle.run_all → run_plugins → post_exec.

Code#

def bootstrap[T](
    *,
    test_cycle: TestCycle[T],
    run_plugins: Callable[[TestCycleResults], None],
    post_exec: Callable[[TestCycleResults], None] | None = None,
    saturate_workers: bool = True,
) -> None:
    results = test_cycle.run_all(saturate_workers=saturate_workers)
    run_plugins(results)
    if post_exec:
        post_exec(results)

Order#

1. cycle.run_all()  →  results
2. run_plugins(results)
3. post_exec(results) (optional)

Step	Effect	Why this order
1	All tests run	We need `results` for the rest
2	Plugins fire (DOCX, JSON, etc.)	Must run before `post_exec` since it can take generation time
3	Post-exec (pretty_print + sys.exit)	Last thing — after this, the process is dead

Typing#

run_plugins: Callable[[TestCycleResults], None]
post_exec: Callable[[TestCycleResults], None] | None = None

Both receive the results as an argument:

03.06 — PEP 695 generics in Ocarina

Wed, 20 May 2026 00:00:00 +0000

03.06 — PEP 695 generics in Ocarina#

Ocarina leans hard on the generics syntax from PEP 695 (Python 3.12+). It’s what keeps the whole typed ecosystem from being a mess.

Three forms of PEP 695#

1. Generic classes#

@final
class Ok[T](_BaseResult):
    value: T
    error: None = None

class TestSuite[Driver]:
    ...

class Watcher[Driver]:
    ...

class ChainRunner[T]:
    ...

class ValidationStartBlock[T]:
    ...

class CliStore[TKeys: str]:  # with bound
    ...

Before PEP 695:

from typing import Generic, TypeVar

T = TypeVar("T")

class Ok(_BaseResult, Generic[T]):
    value: T
    error: None = None

2. Parameterized type aliases#

type Result[T] = Ok[T] | Fail
type Thunk[T] = Callable[[], T]
type Action[T] = Thunk[Result[T]]
type FailureHandler = Callable[[Exception], None]
type Predicate[T] = Callable[[T], None]
type Effect = Callable[[], None]
type TestScenario[Driver] = Callable[[Driver, ILogger], Scenario[Driver]]
type TestScenarioFragment[Driver] = Callable[[Driver, ILogger], TestChain]
type TestChain = Sequence[ChainRunner[Any]]
type TestWatchers[Driver] = Sequence[Watcher[Driver]] | None

Before PEP 695:

04.06 — Property-based testing (hypothesis)

Wed, 20 May 2026 00:00:00 +0000

04.06 — Property-based testing (`hypothesis`)#

A single file (test_invariants_properties.py), but the pattern is interesting: we generate inputs and verify universal properties of the invariant predicates.

The concept#

hypothesis auto-generates test cases that satisfy given constraints, then checks a property holds for every generated case. On failure, hypothesis does shrinking to find the smallest counter-example.

from hypothesis import given, strategies as st

@given(st.integers())
def test_is_positive_passes_on_positive(value):
    if value >= 0:
        is_positive(value)             # must not raise
    else:
        with pytest.raises(InvariantViolationError):
            is_positive(value)         # must raise

→ hypothesis generates integers (typically 100 by default), checks the property on each. Unexpected exception → fail. The shrinker finds the smallest failing case (0? -1? MIN_INT?).

05.06 — Husky + lint-staged + commitlint + commitizen

Wed, 20 May 2026 00:00:00 +0000

05.06 — Husky + lint-staged + commitlint + commitizen#

Strict commit discipline. Conventional, signed, format-checked.

Tools#

Tool	Role
Husky	Installs local Git hooks (`pre-commit`, `commit-msg`)
lint-staged	Runs tools only on staged files
commitlint	Verifies the commit message follows the convention
commitizen + cz-commitlint	Interactive CLI to compose a compliant message

Config#

`.husky/`#

Folder containing the hook scripts:

.husky/
├── pre-commit
└── commit-msg

pre-commit:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
pnpm exec lint-staged

commit-msg:

06.06 — lib/redis.ts + Upstash

Wed, 20 May 2026 00:00:00 +0000

06.06 — `lib/redis.ts` + Upstash#

Source file: lib/redis.ts

Code#

import { Redis } from "@upstash/redis";

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL,
  token: process.env.UPSTASH_REDIS_REST_TOKEN,
});

export default redis;

Why `@upstash/redis` rather than `ioredis`#

Criterion	`ioredis`	`@upstash/redis`
Protocol	TCP / RESP	HTTP / REST
Edge runtime	❌ No	✅ Yes
Connection	Persistent	Per-request
Latency (warm)	< 1ms	50–100ms
Latency (cold)	200ms+	50–100ms
Cost	Variable	Pay-per-request
Setup	Self-hosted Redis	Upstash dashboard (managed)

Edge doesn’t accept persistent TCP connections — each worker is ephemeral. Upstash REST it is.

07.06 — Sacred upload scenarios

Wed, 20 May 2026 00:00:00 +0000

07.06 — Sacred upload scenarios#

The /igoristan/sacred-upload page lets you drag-and-drop a file. Exercises the file-upload pattern on the Ocarina side.

Campaign#

# src/tests/campaigns/sacred_upload.py
def create_igoristan_sacred_upload_campaign(*, drivers_pool) -> TestCampaign:
    return TestCampaign(
        name="Sacred upload",
        suites=[
            create_sacred_upload_happy_paths_test_suite(drivers_pool=drivers_pool),
            create_sacred_upload_unhappy_paths_test_suite(drivers_pool=drivers_pool),
        ],
    )

Scenario: upload files#

# tests/scenarios/sacred_upload/upload_files.py
def scenario_upload_files(driver, logger):
    page = SacredUploadPage(driver=driver)
    fixture_dir = Path(__file__).parent.parent.parent.parent / "pages" / "sacred_upload" / "fixtures"
    file_to_upload = fixture_dir / "sample.png"

    return [
        drive_page(
            act(page, open_sacred_upload_page)...,
            act(page, verify_sacred_upload_page)...,
            act(page, upload_file(file_to_upload))...,
            act(page, verify_file_uploaded(file_to_upload.name))...,
        ),
    ]


test_upload_files = create_selenium_test(
    name="Sacred upload - upload a file",
    test_scenario=lambda driver, logger: Scenario(test_chain=scenario_upload_files(driver, logger)),
)

`<input type="file">`#

class SacredUploadPage(SeleniumTitleMixin, POMBase):
    _file_input = (By.CSS_SELECTOR, "input[type='file']")
    _uploaded_preview = (By.CSS_SELECTOR, ".upload-preview")

    def upload_file(self, file_path: Path) -> SacredUploadPage:
        file_input = self._driver.find_element(*self._file_input)
        file_input.send_keys(str(file_path.resolve()))     # ← Selenium pattern: send_keys on input[type=file]
        return self

    def verify_file_uploaded(self, filename: str) -> SacredUploadPage:
        WebDriverWait(self._driver, get_timeout()).until(
            ec.text_to_be_present_in_element(self._uploaded_preview, filename)
        )
        return self

Standard Selenium pattern: send_keys(<absolute path>) on an input[type=file], even if the input is hidden. Selenium bypasses browser security for file inputs only.

08.06 — Data gaps (G-DATA-1, G-DATA-2)

Wed, 20 May 2026 00:00:00 +0000

08.06 — Data gaps (G-DATA-1, G-DATA-2)#

Two major gaps on data integrity.

G-DATA-1 — No server-side validation of `visit_date`#

Source#

// appointment.php
array_diff_key($_POST, array(
    "facility" => "",
    "hospital_readmission" => "",
    "programs" => "",
    "visit_date" => "",
    "comment" => ""
))

This checks for key presence only. It never validates the value of visit_date.

Symptom#

Empty visit_date: if you strip the HTML5 required attribute via JS and submit with an empty date → booking accepted.
Past visit_date: if you send a backdated booking → booking accepted.
The booking is added to history as-is.

Test	Method
`Appointment - Server accepts empty date when client bypass applied`	Strip the `required` attribute, send with empty booking date → expects rejection by the system (FAIL)
`Appointment - Past date booking accepted`	Send a booking request for yesterday → expects rejection by the system (FAIL)

Both tests fail intentionally — they document the gap.

09.03.06 — Author skills

Wed, 20 May 2026 00:00:00 +0000

09.03.06 — Author skills#

Skills that produce a deliverable. Tests, probes, docs, reports.

Listing (potentially non-exhaustive)#

Skill	Target
`empiricism`	Verify before encoding; don’t crush an intentionally failing gap test
`write-a-probe`	Throwaway “probe” script, gitignored
`write-test-strategy`	Generates the test strategy document from the suite
`extend-coverage`	Extends coverage from existing heritage
`update-frd-and-tests`	Propagates a spec update
`manual-reproduction-guide`	Writes a step-by-step reproduction scenario executable by a human
`manage-backlog`	`BACKLOG.md`
`pr-report`	PR report adapted to context
`plan-test-effort`	First-pass test-effort plan: graded requirements, lightweight risk register, relative effort weights (S / M / L), open questions

`empiricism`#

input  : user intent ("write a test that asserts X")
output : before encoding X:
            1. empirically verify that X is true
                - probe
                - gh api on the source code
                - curl -v to inspect HTTP responses
                - ...
            2. if X confirmed → encode
            3. if X false → correct intent
            4. if X ambiguous → ask the human

“Fair point, I’m assuming. Let me verify empirically.”

09.06 — Public resources

Wed, 20 May 2026 00:00:00 +0000

09.06 — Public resources#

Full table of public URLs exposed by the Holy Book. For humans, LLMs, scrapers.

Listing (potentially non-exhaustive)#

URL	Content	Target audience
`https://mojo-molotov.github.io/ocarina-holy-book/`	Home (EN)	Human
`https://mojo-molotov.github.io/ocarina-holy-book/fr/`	Home (FR)	Human
`https://mojo-molotov.github.io/ocarina-holy-book/ru/`	Home (RU)	Human
`https://mojo-molotov.github.io/ocarina-holy-book/what-is-it`	Article (EN)	Human
`https://mojo-molotov.github.io/ocarina-holy-book/fr/what-is-it`	Article (FR)	Human
`https://mojo-molotov.github.io/ocarina-holy-book/ru/what-is-it`	Article (RU)	Human
… (other doc pages in EN+FR+RU)	…	Human
`https://mojo-molotov.github.io/ocarina-holy-book/llms.txt`	Minimal index for LLMs	LLM
`https://mojo-molotov.github.io/ocarina-holy-book/llms-full.txt`	All content in plaintext	LLM, scraper
`https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.md`	Full project rules	LLM, human (onboarding)
`https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.slim.md`	Short project rules	LLM (context budget)
`https://mojo-molotov.github.io/ocarina-holy-book/ocarina-en.pdf`	A4 PDF docs (EN)	Human (offline)
`https://mojo-molotov.github.io/ocarina-holy-book/ocarina-fr.pdf`	A4 PDF docs (FR)	Human (offline)
`https://mojo-molotov.github.io/ocarina-holy-book/ocarina-ru.pdf`	A4 PDF docs (RU)	Human (offline)
`https://mojo-molotov.github.io/ocarina-holy-book/skills/<name>`	AI skill page	Human, LLM
`https://mojo-molotov.github.io/ocarina-holy-book/assets/content/...`	Images, audio (article covers, illustrations)	Human (inline rendering)

`llms.txt` (emerging standard)#

Spec: https://llmstxt.org/ (proposed in 2024).

10.06 — ocarina-holy-book workflow

Wed, 20 May 2026 00:00:00 +0000

10.06 — `ocarina-holy-book` workflow#

A single workflow: deploy.yml. On push main → VitePress build → upload Pages.

Code#

name: Deploy Ocarina Holy Book

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

env:
  TZ: Europe/Paris

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0 # ← full clone

      - uses: pnpm/action-setup@fcf821c621167805dd63a29662bd7cb5676c81a8
        name: Install pnpm
        with:
          version: 11

      - name: Use Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: "pnpm"

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build
        run: pnpm build

      - uses: actions/upload-pages-artifact@v4
        with:
          path: docs/.vitepress/dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5

Analysis#

1. `TZ: Europe/Paris`#

env:
  TZ: Europe/Paris

Forces the runner timezone to Europe/Paris. Dates rendered by VitePress ("Last update: 05/18/2026 11h42") are in Paris time, not UTC. Leaving it in UTC would cause mysterious date bugs.

12.06 — Yung Innanet (kayos) + VX Underground

Wed, 20 May 2026 00:00:00 +0000

12.06 — Yung Innanet (`kayos`) + VX Underground#

The Holy Book’s most violent passage borrows lyrics from true colors, a track by Yung Innanet (alias kayos), original sysadmin of VX Underground. Yung Innanet died on October 18, 2025 by firearm suicide.

1. Identity#

Field	Value
Music alias	Yung Innanet
Tech handle	kayos (pronounced /kɛjəʊs/)
Twitter	`@yunginnanet`
GitHub	`yunginnanet/yunginnanet`
Recognized role	Original sysadmin of VX Underground
Death	October 18, 2025, firearm suicide
Last.fm profile	Yung Innanet — Last.fm
SoundCloud	vxug.fakedoma.in — SoundCloud

The news of his death wasn’t mainstream-media headlines, consistent with Yung Innanet’s underground profile. It is, however, public within his scene: confirmed notably by tweets from YTCracker and Yung Innanet’s widow. There’s no point dwelling further — this mention exists only to explain a Holy Book quote that wouldn’t make sense without it.

02.03.07 — match_page / when

Wed, 20 May 2026 00:00:00 +0000

02.03.07 — `match_page` / `when`#

Source file: src/ocarina/dsl/testing_with_railway/match_page.py

Bolted onto the framework after the fact. The Holy Book puts it bluntly: “match_page and when were added after the fact; the Igoristan was so random that the use case forced itself onto us. Their implementation was simple, proof of the grammar’s flexibility: other analogous structures could follow just as easily.”

The problem#

Some pages render differently:

Cookies banner showing or not.
A/B test serving two UI variants.
Degraded mode (maintenance page) instead of the real page.
Anti-bot captcha.
…

The scenario needs to branch without breaking the ROP chain.

02.05.07 — TestCycle[Driver] + modes

Wed, 20 May 2026 00:00:00 +0000

02.05.07 — `TestCycle[Driver]` + modes#

Source file: src/ocarina/dsl/testing/oc_test_cycle.py

One job: orchestrate smoke then main campaigns, and apply a smoke-failure-handling mode.

Two modes#

type Mode = Literal[
    "fail-fast-on-first-smoke-campaigns-sequence-fail",
    "wait-for-all-smoke-tests",
]

Mode	Behavior
`fail-fast-on-first-smoke-campaigns-sequence-fail` (default)	First smoke campaign that fails → following ones get skipped.
`wait-for-all-smoke-tests`	Every smoke campaign runs. If any fails, the main campaigns get skipped.

Case	Mode
Dependency-style smoke (e.g. “login” then “dashboard accessible”)	`fail-fast` (login dies → dashboard pointless)
Parallel smoke (e.g. “homepage” + “API ping”)	`wait-for-all` (we want to see both)

fail-fast is the default — it’s the common case.

02.07 — Watcher[Driver]

Wed, 20 May 2026 00:00:00 +0000

02.07 — `Watcher[Driver]`#

Source file: src/ocarina/dsl/testing/watcher.py

Parallelized observer running as a daemon thread alongside the test_chain. Built to catch unpredictable frictions with no direct impact on the scenario that pop up while the scenario runs: random error toasts, parasitic validations, unexpected popups.

The problem#

Holy Book quote (First real-world hurdles):

Even more surprisingly: apps displaying error toasts for no apparent reason, or forms flagging validation errors on inputs that are actually correct, without blocking the journey.

03.07 — Discriminated unions + TypeGuard + @final = sealed unions

Wed, 20 May 2026 00:00:00 +0000

03.07 — Discriminated unions + TypeGuard + @final = “sealed” unions#

The combo that makes Result[T] and TestResult both typed and usable without casts.

Discriminated union#

@final
@dataclass(frozen=True)
class Ok[T](_BaseResult):
    value: T
    error: None = None

@final
@dataclass(frozen=True)
class Fail(_BaseResult):
    error: Exception = field(default_factory=lambda: Exception("Unknown error"))

type Result[T] = Ok[T] | Fail

Two constructors: Ok[T] and Fail.
Discriminant is the isinstance check (not a field like tag: Literal["ok", "fail"]).
Both are @final — no possible subtype. The union is exhaustive, i.e. “sealed”.

Narrowing, `TypeGuard`#

def is_ok[T](result: Result[T]) -> TypeGuard[Ok[T]]:
    return isinstance(result, Ok)

def is_fail[T](result: Result[T]) -> TypeGuard[Fail]:
    return isinstance(result, Fail)

def handle_result(result: Result[int]) -> str:
    if is_ok(result):
        return f"Got: {result.value}"          # mypy: result is Ok[int], so .value exists
    if is_fail(result):
        return f"Error: {result.error}"        # mypy: result is Fail, so .error exists
    # mypy can detect this branch is unreachable (exhaustiveness)

`_BaseResult`#

class _BaseResult:
    error: Exception | None

This base lets you access result.error without narrowing:

04.07 — Coverage policy: what's tested, what isn't, why

Wed, 20 May 2026 00:00:00 +0000

04.07 — Coverage policy: what’s tested, what isn’t, why#

Line coverage is explicitly scoped to the pure DSL and agnostic infra. The rest gets tested by other means (cram, types, snapshots, e2e) or stays out of scope (inert shapes).

`pyproject.toml#tool.coverage.run`#

[tool.coverage.run]
omit = [
    "*/__init__.py",
    "*/tests/*",
    "*/test_*.py",
    "src/ocarina/custom_errors/*",
    "src/ocarina/custom_types/*",
    "src/ocarina/ports/*",
    "src/ocarina/opinionated/loggers/custom_types/*",
    "src/**/*singleton.py",
    "src/**/consts/**",
    # Selenium adapter layer — exercised only against a real browser.
    "src/ocarina/infra/selenium/*",
    "src/ocarina/dsl/testing/selenium/*",
    "src/ocarina/opinionated/cli/selenium/*",
    "src/ocarina/pom/selenium/muted.py",
    # Playwright adapter layer — exercised only against a real browser.
    "src/ocarina/infra/playwright/*",
    "src/ocarina/dsl/testing/playwright/*",
    "src/ocarina/opinionated/cli/playwright/*",
    "src/ocarina/pom/playwright/*",
    "src/ocarina/opinionated/cli/phantoms.py",
    # Opinionated loggers — only file_logger.py stays in scope.
    "src/ocarina/opinionated/loggers/create_matching_logger.py",
    "src/ocarina/opinionated/loggers/muted_logger.py",
    "src/ocarina/opinionated/loggers/print_logger.py",
    "src/ocarina/opinionated/loggers/print_and_file_logger.py",
    "src/ocarina/opinionated/loggers/utils/*",
    # Traversed by cram tests
    "src/ocarina/opinionated/cli/store.py",
    "src/ocarina/opinionated/cli/builder.py",
]

Categories#

1. Obvious exclusions#

Pattern	Justification
`*/__init__.py`	Empty modules (Python 3 often doesn’t need them)
`/tests/`, `/test_.py`	Tests don’t test themselves

2. Types / errors / ports / shapes#

Path	Justification
`src/ocarina/custom_types/*`	Just `type X = ...` and frozen dataclasses. No runtime logic.
`src/ocarina/custom_errors/*`	Just Exception subclasses. No logic.
`src/ocarina/ports/*`	ABCs and Protocols. No behavior.
`src/ocarina/opinionated/loggers/custom_types/*`	id.
`src//consts/`	Constants (`LOGGERS_CHOICES = (...)`).
`src/*/singleton.py`	Trivial Singleton wrappers.

3. Selenium and Playwright layers (e2e only)#

Path	Justification
`src/ocarina/infra/selenium/*`	Real Selenium code (`Chrome()`, `Firefox()`). Only runs with a real browser.
`src/ocarina/dsl/testing/selenium/*`	`create_selenium_test`, `create_selenium_watcher` (trivial factories on `Test` / `Watcher`).
`src/ocarina/opinionated/cli/selenium/*`	`create_selenium_*_cli_store` (reads `platform.system`, instantiates).
`src/ocarina/pom/selenium/muted.py`	Utility `MutedPOM` (nearly empty).
`src/ocarina/infra/playwright/*`	Real Playwright code + the `PlaywrightDriver` actor. The end-to-end only proves out against a real browser.
`src/ocarina/dsl/testing/playwright/*`	`create_playwright_test`, `create_playwright_watcher` (same trivial factories).
`src/ocarina/opinionated/cli/playwright/*`	`create_playwright_cli_store` (Playwright CLI).
`src/ocarina/pom/playwright/*`	`MutedPlaywrightPOM` + `mixins` (Null Object, nearly empty).

These files are covered by:

05.07 — Igoristan CI/CD

Wed, 20 May 2026 00:00:00 +0000

05.07 — Igoristan CI/CD#

Two workflows: ci-pr.yml on PR (3 parallel jobs), deploy.yml on push main (GitHub Pages).

`ci-pr.yml`#

name: CI/PR

on:
  pull_request:
    branches: ["**"]
  workflow_dispatch:

defaults:
  run:
    shell: bash

jobs:
  format-check:
    runs-on: ubuntu-latest
    env:
      WIREIT_CACHE: github
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v5
        with: { version: 11 }
      - uses: actions/setup-node@v6
        with: { node-version: 24, cache: "pnpm" }
      - uses: google/wireit@setup-github-actions-caching/v2
      - name: Install project
        run: make install
      - name: Formatcheck
        run: make ci:format-check

  lint:
    runs-on: ubuntu-latest
    env:
      WIREIT_CACHE: github
    steps:
      # ... same ...
      - uses: actions/cache@v5
        with:
          path: .eslintcache
          key: eslint-cache-${{ hashFiles('eslint.config.ts', 'src/**/*.*', 'package.json') }}
      - name: Lint
        run: pnpm lint

  typecheck:
    runs-on: ubuntu-latest
    env:
      WIREIT_CACHE: github
    steps:
      # ... same ...
      - name: Typecheck
        run: pnpm typecheck

Job	Command	Cache
`format-check`	`pnpm exec prettier . --check` (via wireit)	wireit + node_modules
`lint`	`pnpm exec eslint ... --max-warnings 0 --cache`	wireit + `.eslintcache` (actions/cache)
`typecheck`	`tsc --build --pretty tsconfig.json`	wireit + `tsbuildinfo`

                          PR opened / push
                                  │
                ┌─────────────────┼─────────────────┐
                ▼                 ▼                 ▼
        ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
        │ format-check │ │     lint     │ │  typecheck   │
        │ (1-2 minutes)│ │ (1-2 minutes)│ │ (1-2 minutes)│
        └──────────────┘ └──────────────┘ └──────────────┘
                │                 │                 │
                └─────────────────┴─────────────────┘
                                  ▼
                             PR mergeable

`deploy.yml`#

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v5
        with: { version: 11 }
      - uses: actions/setup-node@v6
        with: { node-version: 24, cache: "pnpm" }
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      - name: Build
        run: pnpm build
      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v4
        with: { path: dist/client }

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5

Job	Effect
`build`	`pnpm install --frozen-lockfile` → `pnpm build` (= `wireit build` = `lint → typecheck → vike build`) → upload `dist/client`
`deploy`	`actions/deploy-pages@v5` → publishes the artifact → URL = https://mojo-molotov.github.io/igoristan/

`concurrency: pages` + `cancel-in-progress: false`#

concurrency:
  group: "pages"
  cancel-in-progress: false

Prevents two simultaneous deployments (race condition).
The second waits (cancel-in-progress: false → we don’t cancel the running one).

06.07 — OTP coordination flow + deliberate imprecision

Wed, 20 May 2026 00:00:00 +0000

06.07 — OTP coordination flow + deliberate imprecision#

The backend’s reason to exist: let N parallel Ocarina workers retrieve the right OTP for their user, even when several OTPs are generated.

Flow#

   ┌───────────────────────────────────────────────────────────────────┐
   │               Worker (among --workers 3 of Ocarina)               │
   └───────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ Selenium opens the Dashboard login page                           │
   └─────────────────────────────────┬─────────────────────────────────┘
                                     ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ Acquire the distributed Redis lock (OTP_SEND_LOCK_KEY)            │
   │   → only this worker can click "Send OTP" during ACQ              │
   └─────────────────────────────────┬─────────────────────────────────┘
                                     ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ min_utc_date = datetime.now(UTC)                                  │
   └─────────────────────────────────┬─────────────────────────────────┘
                                     ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ L1 cache: record min_utc_date + username in the cache             │
   │   (keys reserved by reserve_free_cache_key)                       │
   └─────────────────────────────────┬─────────────────────────────────┘
                                     ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ Selenium types username + password + ticks OTP + click "REQ OTP"  │
   └─────────────────────────────────┬─────────────────────────────────┘
                                     ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ IGORISTAN UI: fetch /api/otp?_user=<username>                     │
   │   (x-api-key typed by Selenium into the UI)                       │
   └─────────────────────────────────┬─────────────────────────────────┘
                                     ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ TESTS-WORKERS /api/otp:                                           │
   │   generate(secret) → otpCode                                      │
   │   createdAt = floor(now/1000)*1000  ← ms stripped                 │
   │   event = { _user, otpCode, createdAt, expiresAt, ... }           │
   │   redis.set("otp:<now>:<uuid>", JSON, EX 360)                     │
   │   return event                                                    │
   └──────────────────────────────────┬────────────────────────────────┘
                                      ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ IGORISTAN UI: displays OTP screen                                 │
   └──────────────────────────────────┬────────────────────────────────┘
                                      ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ Release the OTP_SEND_LOCK_KEY Redis lock                          │
   └──────────────────────────────────┬────────────────────────────────┘
                                      ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ Selenium: retrieve_dashboard_otp_code(min_utc_date, _user)        │
   │   ↓                                                               │
   │   GET /api/otp-history  (x-api-key = IGOR_API_KEY)                │
   │   ↓                                                               │
   │   TESTS-WORKERS: SCAN otp:* + MGET → all events                   │
   │   ↓                                                               │
   │   client-side filter by _user                                     │
   │   filter createdAt >= min_utc_date - 1s                           │
   │   sort ASC by createdAt                                           │
   │   return first.otpCode                                            │
   └──────────────────────────────────┬────────────────────────────────┘
                                      ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ Selenium types the OTP into the Igoristan UI                      │
   │   → AUTHENTICATED_WITH_MFA                                        │
   └───────────────────────────────────────────────────────────────────┘

Race conditions#

Worker A: min_utc_date_A = 13:27:53.123, generates OTP_A at 13:27:53.250.
Worker B: min_utc_date_B = 13:27:53.130, generates OTP_B at 13:27:53.470.

Without coordination, A could pick up OTP_B instead of OTP_A — the timestamps are close and truncated to the second.

07.07 — HumanizedDriver

Wed, 20 May 2026 00:00:00 +0000

07.07 — `HumanizedDriver`#

Source file: src/lib/ext/selenium/humanize/proxy.py

Proxy pattern: wraps a Selenium WebDriver and intercepts only find_element* to return WebElements whose send_keys are humanized (slow typing with typos, hesitations, corrections).

Code#

class HumanizedDriver(WebDriver):
    def __init__(self, driver: WebDriver, **keyboard_config: Unpack[KeyboardConfig]) -> None:
        object.__init__(self)
        self._driver = driver
        self._config = keyboard_config

    def find_element(self, by: str | RelativeBy = "id", value: str | None = None) -> _HumanizedWebElement:
        element = self._driver.find_element(by, value)
        return _HumanizedWebElement(element, self._config)

    def find_elements(self, by: str | RelativeBy = "id", value: str | None = None) -> list[WebElement]:
        elements = self._driver.find_elements(by, value)
        return [_HumanizedWebElement(el, self._config) for el in elements]

    def __getattr__(self, name: str):
        return getattr(self._driver, name)

1. Inherits from `WebDriver`#

class HumanizedDriver(WebDriver):

HumanizedDriver passes isinstance(x, WebDriver) checks.

08.07 — Spec gaps (G-SPEC-1 to G-SPEC-3)

Wed, 20 May 2026 00:00:00 +0000

08.07 — Spec gaps (G-SPEC-1 to G-SPEC-3)#

Three gaps on business behavior vs the expected spec of a healthcare system.

G-SPEC-1 — History sorted by submission order, not by date#

Source#

// views/page_history.php
foreach ($_SESSION['history'] as $appointment) {
    // ... render ...
}

No usort. No sort. No sort step exists anywhere.

appointment.php pushes with array_push($_SESSION['history'], $_POST) — append to the end (it’s a pushback).

Unmet spec#

REQ-HIST-3 from the FRD:

09.03.07 — Refactor skills

Wed, 20 May 2026 00:00:00 +0000

09.03.07 — Refactor skills#

Skills that refactor the existing automated-test base.

Listing (potentially non-exhaustive)#

Skill	Target
`refactor-fragmentation`	DRY based on user preference
`introduce-pom-retries`	POM-internal retries, with split (first-try + with-retries)

`refactor-fragmentation`#

input  : the test base
output : DRY refactor suggestions:
            - blocks repeated in 3+ scenarios → extract into a fragment
            - near-identical connectors → extract a parameterized connector
            - repeated log+screenshot sequences → extract a helper
         + per-case recommendation

CLAUDE.md:

10.07 — tests-workers: no GitHub CI, auto Vercel deploy

Wed, 20 May 2026 00:00:00 +0000

10.07 — `tests-workers`: no GitHub CI, auto Vercel deploy#

The only repo in the ecosystem without a GitHub Actions workflow. Everything goes through Vercel.

Content of `.github/`#

tests-workers/
└── (no .github/ — no workflows)

No ci.yml. No deploy.yml. No GitHub action.

`vercel.json`#

{
  "version": 2,
  "buildCommand": "echo 'No build required'",
  "outputDirectory": ".",
  "framework": null
}

Vercel detects the project as TypeScript Edge Functions, builds on the fly (transpiles TS at runtime).

`package.json#scripts`#

{
  "scripts": {
    "vercel-build": "echo 'Build skipped'"
  }
}

vercel-build hook: echo no-op.
Vercel doesn’t try to build.

12.07 — The underlying movement

Wed, 20 May 2026 00:00:00 +0000

12.07 — The underlying movement#

Three possible trajectories for anyone in the 1999-2012 hacker scene: (1) stay black hat and end up in prison (at best), (2) drop off entirely, (3) rebuild oneself alone through Research. The Holy Book speaks of the third. That’s where Ocarina comes from.

1. The key passage from the Holy Book#

From Hell to where we are today.
Saved by Research, by good values, by thankless work. Not the kind that makes you shine. The kind passed down by those who know how to detect a potential and save it before it’s too late.

02.05.08 — filter_tests_by_ids

Wed, 20 May 2026 00:00:00 +0000

02.05.08 — `filter_tests_by_ids`#

Source file: src/ocarina/dsl/testing/filter_tests_by_ids.py

Called by TestSuite.__init__ to apply the CLI flags --only <ids> and --exclude <ids>. Mutually exclusive — can’t pass both.

Code#

def filter_tests_by_ids[Driver](
    tests: Sequence[Test[Driver]],
    *,
    only: Iterable[str] = (),
    exclude: Iterable[str] = (),
    logger: ILogger,
) -> Sequence[Test[Driver]]:
    only_set = set(only)
    exclude_set = set(exclude)

    if only_set and exclude_set:
        raise ValueError("--only and --exclude cannot be used together")

    known_ids = {test.test_id for test in tests}

    if only_set:
        matched = only_set & known_ids
        if matched:
            joined = ", ".join(sorted(matched))
            logger.info(f"--only: matched test IDs: {joined}")
        return [test for test in tests if test.test_id in only_set]

    if exclude_set:
        matched = exclude_set & known_ids
        if matched:
            joined = ", ".join(sorted(matched))
            logger.info(f"--exclude: matched test IDs: {joined}")
        return [test for test in tests if test.test_id not in exclude_set]

    return tests

Four guarantees#

1. Mutex `--only` / `--exclude`#

if only_set and exclude_set:
    raise ValueError("--only and --exclude cannot be used together")

Passing both is a runtime error (not a mypy one). Semantically nonsense: “keep only A, B” AND “exclude C, D”? At the CLI level, doesn’t make sense. The mutex kills ambiguity.

02.08 — POMBase

Wed, 20 May 2026 00:00:00 +0000

02.08 — `POMBase`#

Source file: src/ocarina/pom/base.py

Framework-agnostic abstract base for the Page Object Model. Two required methods. Zero mention of Selenium.

Code#

class POMBase(ABC):
    @abstractmethod
    def verify(self, *, timeout: float | None = None) -> Self:
        ...

    @abstractmethod
    def get_current_title(self) -> str:
        ...

Six bytes of contract (the two signatures). That’s all.

Why two methods#

`verify(timeout=None) -> Self`#

Purpose: prove we’re on the right page. Otherwise, raise.

timeout lets you wait up to a given time for the page to load (handy for Selenium WebDriverWait).
None default lets the implementation decide (typically reading get_timeout() which reads the CLI).
Returning Self enables fluent method chaining (MyPage(...).open().verify().click()).

The only method test-side that’s truly needed to guarantee “I’m on the page I want.” Everything else (click_xxx, enter_xxx) is on the subclass.

04.08 — Allure + composite action allure-history + GH Pages deploy

Wed, 20 May 2026 00:00:00 +0000

04.08 — Allure + composite action `allure-history` + GH Pages deploy#

The Allure report gets generated on every CI, archived on a dedicated Git branch, then published on GitHub Pages. Live URL: https://mojo-molotov.github.io/ocarina/allure-report/.

Pipeline#

┌────────────────────────────────────────────────────────┐
│ main_ci.yml (push/PR main, or dispatch)                │
└──────────────────┬─────────────────────────────────────┘
                   ▼
   ┌───────────────────────────────────┐
   │ job : test                        │
   │  - matrix (ubuntu / windows × py) │
   │  - make test (cram + pytest)      │
   │  - upload-artifact allure-results │
   └───────────────┬───────────────────┘
                   ▼
   ┌───────────────────────────────────┐
   │ job : allure-history              │
   │  - download all allure-results    │
   │  - local composite action:        │
   │       allure-history/action.yml   │
   │  - upload-artifact allure-report  │
   └───────────────┬───────────────────┘
                   ▼
   ┌───────────────────────────────────┐
   │ job : deploy                      │
   │  - download allure-report         │
   │  - prepare pages-root/            │
   │  - actions/upload-pages-artifact  │
   │  - actions/deploy-pages           │
   └───────────────────────────────────┘

`allure-history`#

.github/actions/allure-history/action.yml: composite action local to the repo (uses: ./.github/actions/allure-history).

07.08 — L1 cache + reserved keys + distributed Redis locks

Wed, 20 May 2026 00:00:00 +0000

07.08 — L1 cache + reserved keys + distributed Redis locks#

Internal coordination mechanics: an in-memory cache to share values within a test, a Redis lock to serialize a click across several workers.

L1 cache#

# src/caches/l1.py
from dogpile.cache import make_region

in_memory_cache_with_30m_ttl = make_region().configure(
    "dogpile.cache.memory", expiration_time=30 * 60
)

One global cache, dogpile.cache.memory backend, 30-minute TTL. Everything in RAM — no Redis for local-process state.

Why an L1 cache?#

Ocarina’s DSL is static: a scenario describes a sequence of acts. But sometimes you need to share a value between two acts:

08.08 — Chrome BFCache (B-BROWSER-1) + environment artifacts

Wed, 20 May 2026 00:00:00 +0000

08.08 — Chrome BFCache (B-BROWSER-1) + environment artifacts#

Chrome restores a no-store page after logout, from the BFCache, even though it’s a page protected by authentication.

B-BROWSER-1 — Chrome’s BFCache is a pain#

Symptom#

After logout, clicking the back button to be redirected to a page that was protected by authentication (e.g. history.php):

Chrome: the page stays displayed with its contents as shown to a still-authenticated user. The URL remains history.php, and the server isn’t re-contacted to validate or invalidate access.
Firefox: a new request goes to the server, which sees the session is dead and redirects.

Very annoying gap#

history.php correctly sends:

09.03.08 — State skill

Wed, 20 May 2026 00:00:00 +0000

09.03.08 — State skill#

A single skill: question-state. Interrogates the environment before believing a result.

The skill#

input  : a surprising result ("the test fails")
output : a series of questions about state:
            - which browser are we running on?
            - which commit?
            - is the SUT warm or cold?
            - is Redis available?
            - what's the configured wait-timeout?
            - what's the driver version?
            - does ChromeDriver have its password-manager-off fix?
            - is this an isolated run or a parallel run?
            - are other tests touching the same SUT resources?

Approach#

CLAUDE.md:

12.08 — Ocarina in the testing industry

Wed, 20 May 2026 00:00:00 +0000

12.08 — Ocarina in the testing industry#

Ocarina isn’t a better pytest, isn’t a better Robot Framework, isn’t a better Cypress. It’s structurally elsewhere. This chapter tries to explain the shift it represents and the head start it takes.

1. The current industry map#

Three big e2e tool families#

Family	Examples	Model
Text DSLs	Robot Framework, Cucumber + Gherkin	Permanent translation layer between text and code
Runner plugins	pytest-selenium, pytest-playwright, pytest-bdd	Grafted onto pytest, inherit its lifecycle
Vendor SaaS	BrowserStack, Sauce Labs, LambdaTest, Cypress Dashboard	Local runner + paid execution cloud

Three shared friction surfaces#

Friction	Manifestation
Marketing > Technical	Tools sold on demos, conferences, and oriented certifications. Hype drives adoption.
Vendor lock-in	Once adopted, refactor is costly, hostage taking.
Misplaced cognitive effort	Understanding the tool takes longer than doing the work.

2. Ocarina’s technical bet#

No text DSL → pure Python, embedded DSL.
No pytest plugin → integrated runner, absolute ISTQB fidelity.
No async/await → simplicity, Selenium-synchronous compatibility, no “geek tricks”.
No SaaS → all local, very dense core, white box.

02.09 — Ports: ILogger, ITakeScreenshot

Wed, 20 May 2026 00:00:00 +0000

02.09 — Ports: `ILogger`, `ITakeScreenshot`#

Source folder: src/ocarina/ports/

Two ports. That’s it. Everything else (WebDriversPool, Screenshotter, etc.) lives under infra/, not ports/. The line is sharp: a port is an abstraction the DSL sits on; an infra is the implementation of adapters.

`ILogger`#

class ILogger(ABC):
    @abstractmethod
    def set_prefix(self, prefix_thunk: Thunk[str]) -> Self: ...

    @abstractmethod
    def set_domain_taxonomy(self, taxonomy: tuple[str, ...]) -> Self: ...

    @abstractmethod
    def raw(self, *args: object, stream: SupportsWrite[str] | None = None, **kwargs: object) -> None: ...

    @abstractmethod
    def critical(self, msg: str, *args, exc: Exception | None = None, **kwargs) -> None: ...

    @abstractmethod
    def error(self, msg: str, *args, exc: Exception | None = None, **kwargs) -> None: ...

    @abstractmethod
    def warning(self, msg: str, *args, exc: Exception | None = None, **kwargs) -> None: ...

    @abstractmethod
    def info(self, msg: str, *args, exc: Exception | None = None, **kwargs) -> None: ...

    @abstractmethod
    def debug(self, msg: str, *args, exc: Exception | None = None, **kwargs) -> None: ...

    @abstractmethod
    def test_name(self, msg: str, *args, exc: Exception | None = None, **kwargs) -> None: ...

    @abstractmethod
    def success(self, msg: str, *args, exc: Exception | None = None, **kwargs) -> None: ...

    @abstractmethod
    def exception(self, msg: str, *args, exc: Exception | None = None, **kwargs) -> None: ...

    @abstractmethod
    def cleanup(self) -> None: ...

Method	Semantics
`set_prefix(thunk)`	Lazy prefix applied on every log (for timestamps, threads…). Returns `Self` for chaining.
`set_domain_taxonomy(taxonomy)`	Sets the domain hierarchy (`(cycle, campaign, suite, test)`). Critical for `FileLogger`, which builds a file tree.
`raw(*args, stream=None)`	Raw write, no format (used by the report plugins).
`critical / error / warning / info / debug`	Standard levels. Every method accepts `exc=` to pass an exception and format it.
`test_name(msg)`	Custom level: announces the running test (`logger.test_name(test.name)`).
`success(msg)`	Custom level: passed assertion (used by the `.success(...)` handlers).
`exception(msg, exc=)`	Logs an exception with the full traceback.
`cleanup()`	End-of-life: flush + close (for `FileLogger`). Recycles the log file between retries.

Three things that are not in `ILogger`#

No set_level(): level handling is the implementation’s call (e.g., MutedLogger filters everything).
No add_handler(): no logging.Logger-style stdlib API. Composition happens by instantiating different loggers (PrintAndFileLogger wraps both).
No child(name): taxonomy is passed as a block via set_domain_taxonomy.

`set_prefix(thunk)`#

logger.set_prefix(lambda: f"[{datetime.now().isoformat()}]")

A str would be computed at set_prefix time and frozen. A Thunk recomputes the prefix on every log call. Perfect for timestamps.

07.09 — catch_me_if_you_can

Wed, 20 May 2026 00:00:00 +0000

07.09 — `catch_me_if_you_can`#

Detects parasite elements that pop on the page while the test is running, and traces them.

Callback#

# src/lib/ext/selenium/watchers/catch_me_if_you_can_watcher.py
def catch_me_if_you_can_cb(watcher: SeleniumWatcher) -> None:
    elements = watcher.driver.execute_script(
        "return Array.from(document.querySelectorAll('.catch-me-if-you-can'));"
    )

    if not elements:
        return

    raw = watcher.driver.execute_script(
        """
        return arguments[0].map(el => ({
            tag:       el.tagName.toLowerCase(),
            text:      el.innerText.trim(),
            id:        el.id,
            cls:       el.className,
            name:      el.getAttribute('name') || '',
            testid:    el.getAttribute('data-testid') || '',
        }));
        """,
        elements,
    )

    for attrs in raw:
        fingerprint = ":".join(
            filter(
                None,
                [
                    attrs["tag"],
                    attrs["text"],
                    attrs["id"],
                    attrs["cls"],
                    attrs["name"],
                    attrs["testid"],
                ],
            )
        )

        if fingerprint in watcher.cache:
            continue

        watcher.cache.add(fingerprint)
        watcher.report(
            f"catch-me-if-you-can element detected: <{attrs['tag']}> {attrs['text']!r}",
            label="CATCH_ME_IF_YOU_CAN",
        )

Mechanics#

1. Javascript to bypass implicit wait#

elements = watcher.driver.execute_script(
    "return Array.from(document.querySelectorAll('.catch-me-if-you-can'));"
)

Not find_elements(By.CSS_SELECTOR, ...).

08.09 — CI: ai_proof_ci.yml + ai_proof_e2e.yml

Wed, 20 May 2026 00:00:00 +0000

08.09 — CI: `ai_proof_ci.yml` + `ai_proof_e2e.yml`#

Two workflows. Fast PR (lint+typecheck). Manual e2e with a Firefox/Chrome matrix + Heroku warm-up + ChromeDriver stacktrace filtering.

`ai_proof_ci.yml`#

name: ai_proof CI

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:

defaults:
  run:
    shell: bash

jobs:
  lint-and-typecheck:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.14"
          allow-prereleases: true
      - uses: actions/cache@v4
        with:
          path: .venv
          key: venv-${{ runner.os }}-py${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('pyproject.toml') }}
      - name: Install dependencies
        if: steps.cache-venv.outputs.cache-hit != 'true'
        run: |
          python -m venv .venv
          .venv/bin/pip install . ruff mypy mypy-extensions typing-extensions pre-commit

      - name: Ruff format check
        run: .venv/bin/ruff format src/ --check

      - name: Ruff lint
        run: .venv/bin/ruff check src/

      - name: Mypy
        run: .venv/bin/mypy src/

Step	Cmd
Ruff format check	`ruff format src/ --check`
Ruff lint	`ruff check src/`
Mypy	`mypy src/`

`ai_proof_e2e.yml`#

name: ai_proof e2e

on:
  workflow_dispatch:

defaults:
  run:
    shell: bash

jobs:
  e2e:
    name: e2e (${{ matrix.browser }})
    runs-on: ubuntu-latest
    env:
      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
      WAIT_TIMEOUT: 15
    strategy:
      fail-fast: false
      matrix:
        include:
          - browser: firefox
            driver: geckodriver
          - browser: chrome
            driver: chromedriver

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.14"
          allow-prereleases: true
      - uses: actions/cache@v4
        with:
          path: .venv
          key: venv-${{ runner.os }}-py${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('pyproject.toml') }}
      - name: Install dependencies
        if: steps.cache-venv.outputs.cache-hit != 'true'
        run: |
          python -m venv .venv
          .venv/bin/pip install . ruff mypy mypy-extensions typing-extensions pre-commit

      # --- Firefox ---

      - name: Install geckodriver
        if: matrix.browser == 'firefox'
        run: |
          GECKO_VERSION=0.36.0
          wget -q https://github.com/mozilla/geckodriver/releases/download/v$GECKO_VERSION/geckodriver-v$GECKO_VERSION-linux64.tar.gz
          tar -xzf geckodriver-v$GECKO_VERSION-linux64.tar.gz
          chmod +x geckodriver

      - name: Setup Firefox
        if: matrix.browser == 'firefox'
        uses: browser-actions/setup-firefox@fcf821c621167805dd63a29662bd7cb5676c81a8

      # --- Chrome ---

      - name: Install chromedriver
        if: matrix.browser == 'chrome'
        run: |
          CHROME_VER=$(google-chrome-stable --version | grep -oP '\d+\.\d+\.\d+\.\d+')
          wget -q -O chromedriver.zip \
            "https://storage.googleapis.com/chrome-for-testing-public/${CHROME_VER}/linux64/chromedriver-linux64.zip"
          unzip -q chromedriver.zip
          mv chromedriver-linux64/chromedriver ./chromedriver
          chmod +x ./chromedriver

      # --- Warm-up ---

      - name: Warm up Heroku dyno
        run: |
          # CURA runs on a Heroku dyno that sleeps after inactivity.
          # Tests hitting a cold dyno produce timeouts (false fails) and slow
          # confirmations (false passes on gap tests). Wake it explicitly
          # before any browser opens.
          curl -sf --retry 6 --retry-delay 5 --retry-all-errors \
            --max-time 30 https://katalon-demo-cura.herokuapp.com/ > /dev/null
          echo "Dyno is warm"

      # --- Run ---

      - name: Run e2e cycle
        run: |
          # ChromeDriver release builds ship without debug symbols. On errors it
          # dumps raw C++ stack frames ("#N 0x<addr> <unknown>") into the WebDriver
          # response, which Selenium surfaces as the exception message — polluting
          # both the live log and the pretty-print summary with unreadable hex noise.
          # No Python-side fix exists. Strip the frames with sed before they land.
          # pipefail preserves Python's exit code through the pipe.
          set -o pipefail
          .venv/bin/python -u src/main.py \
            --driver-path ./${{ matrix.driver }} \
            --browser ${{ matrix.browser }} \
            --workers 3 \
            --wait-timeout ${{ env.WAIT_TIMEOUT }} \
            --logger terminal+file \
            2>&1 | sed -u \
              -e '/Stacktrace:/{N;/\n#[0-9][0-9]* 0x[0-9a-f][0-9a-f]* <unknown>/{s/Stacktrace:\n[^\n]*/HIDDEN/;b};P;D}' \
              -e '/^#[0-9][0-9]* 0x[0-9a-f][0-9a-f]* <unknown>/d'

      - name: Enumerate traces
        if: always()
        run: |
          sync
          find $GITHUB_WORKSPACE/.screenshots -type f 2>/dev/null || true
          find $GITHUB_WORKSPACE/.ocarina_logs -type f 2>/dev/null || true
          find $GITHUB_WORKSPACE/.reports -type f 2>/dev/null || true

      - name: Upload screenshots
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: screenshots-${{ matrix.browser }}
          path: .screenshots/
          retention-days: 7

      # … upload logs, reports similarly ...

Analysis#

`fail-fast: false`#

strategy:
  fail-fast: false
  matrix:
    include:
      - browser: firefox
      - browser: chrome

fail-fast: false — if Firefox fails, Chrome continues. Essential: the point of the run is seeing both browsers, even when one fails.

09.03.09 — Setup skills

Wed, 20 May 2026 00:00:00 +0000

09.03.09 — Setup skills#

Two skills: setup-environment (onboarding a new contributor, human or AI) and profile-environment (governing how much latitude the engagement grants the LLM). Both feed the suite’s assembled CLAUDE.md.

The skill#

input  : a fresh repo
output : onboarding steps:
            1. venv
            2. pip install (dev deps + ocarina)
            3. ruff / mypy / pre-commit installed
            4. CLAUDE.local.md created (paths requested from user)
            5. runner smoke-check (minimal test that validates everything works)
            6. pre-commit loop tested

Step 1: venv#

python -m venv .venv
source .venv/bin/activate

Step 2: pip install#

pip install . ruff mypy mypy-extensions typing-extensions pre-commit

Step 3: dev tooling#

pre-commit install --config .pre-commit-config.yaml

Step 4: `CLAUDE.local.md`#

CLAUDE.local.md is gitignored and contains machine-specific paths.

12.09 — Ecosystem coherence

Wed, 20 May 2026 00:00:00 +0000

12.09 — Ecosystem coherence#

Six repos, several languages, several technologies, several licenses, several deployment platforms. At first glance, heterogeneous. On a second read, rigorously coherent: every piece serves exactly the same bet.

1. Overview: six repos, one ethic#

┌────────────────────────────────────────────────────────────────────────┐
│         THE ECOSYSTEM AS A COHERENT WHOLE                              │
└────────────────────────────────────────────────────────────────────────┘

  ┌──────────────┐    The framework. ROP, strict types, refusal of pytest
  │   ocarina    │    plugin. ONE single runtime dep. Auditable in an
  └─────────────┬┘    afternoon. — PROVES that rigor is lightweight.
                │
                │
                ▼
  ┌─────────────────┐ The reference of use. Project adapters. Canonical
  │ ocarina-example │ patterns. Shows how to narrow the framework's API
  └─────────────┬───┘ surface for your context. — PROVES the framework is
                │     usable "by anyone".
                │
                ▼
  ┌─────────────────────────┐ The AI bet. Co-written by Claude 99%. CURA
  │ ocarina-with-ai-example │ Healthcare as SUT. Findings sourced down to PHP.
  └─────────────┬───────────┘ — PROVES AI + Ocarina can do real senior-tester
                │               work.
                ▼
       ┌──────────────┐ The deliberately chaotic SUT. The playground.
       │  igoristan   │ — PROVES you can test a pathological app without
       └────────┬─────┘   cheating.
                │
                ▼
       ┌────────────────┐ The coordination backend. Vercel Edge,
       │ tests-workers  │ Upstash Redis, deliberate anti-precision.
       └────────┬───────┘ — PROVES you can do distributed coordination
                │           without a proprietary platform.
                │
                ▼
       ┌───────────────────┐ The public documentation. VitePress + FR/EN/RU
       │ ocarina-holy-book │ + LLM-first (llms.txt, CLAUDE.md, skills).
       └───────────────────┘ — PROVES you can write docs that serve human AND
                               AI, without a third-party platform.

2. One repo = one type of challenge#

Repo	Type of challenge	Bet proven
`ocarina`	Build a small and deep framework	“Rigor isn’t a gas factory”
`ocarina-example`	Demonstrate canonical usage	“You can actually write rigorous tests like this”
`ocarina-with-ai-example`	Make a human and an AI collaborate	“AI is the bridge, not the DSL”
`igoristan`	Build a chaotic SUT	“Not a demo on a twenty-HTML-line site — a demo on a real mess”
`tests-workers`	Be the substrate testers coordinate through	“You can be stateless on the code side”
`ocarina-holy-book`	Document for humans and AI	“Documentation is first and foremost raw data for LLMs”

Remove one of these repos and the ecosystem loses an argument. The six are solidary.

07.10 — EnvGetters

Wed, 20 May 2026 00:00:00 +0000

07.10 — `EnvGetters`#

Typed accessor for environment variables. Avoids typos, refuses unknown keys at compile time, brings IDE autocomplete.

Code#

# src/lib/ext/ocarina/adapters/agnostic/env_getters.py
from typing import Literal
from types import MappingProxyType
from ocarina.opinionated.infra.env import EnvGetters, Effects

type _CredsKeys = Literal["dashboard"]
type _ValuesKeys = Literal["igor_api_key", "redis_url"]


def _load_env() -> None:
    from dotenv import load_dotenv
    load_dotenv()


_DEFAULT_EFFECTS = (_load_env,)


class _EnvGetters(EnvGetters[_CredsKeys, _ValuesKeys]):
    def __init__(self, *, effects: Effects) -> None:
        for effect in effects:
            effect()
        super().__init__(
            credentials={
                "dashboard": MappingProxyType({
                    "login": os.environ["DASH_USERNAME"],
                    "password": os.environ["DASH_PASSWORD"],
                }),
            },
            values={
                "igor_api_key": os.environ["IGOR_API_KEY"],
                "redis_url": os.environ["REDIS_URL"],
            },
        )


def create_env_getters(*, effects: Effects | None = None) -> _EnvGetters:
    if effects is None:
        effects = _DEFAULT_EFFECTS
    return _EnvGetters(effects=effects)

`_CredsKeys` and `_ValuesKeys`#

type _CredsKeys = Literal["dashboard"]
type _ValuesKeys = Literal["igor_api_key", "redis_url"]

Credentials: login/password pairs (immutable dict via MappingProxyType).
Values: raw values.

`MappingProxyType`#

"dashboard": MappingProxyType({
    "login": os.environ["DASH_USERNAME"],
    "password": os.environ["DASH_PASSWORD"],
}),

MappingProxyType is a read-only wrapper around a dict:

09.03.10 — Run skills

Wed, 20 May 2026 00:00:00 +0000

09.03.10 — Run skills#

Surface the choices to make before a local dispatch, compose the command, and hand it back. The skill never launches the run itself.

Listing (potentially non-exhaustive)#

Skill	Target
`propose-visual-review`	Offer headed (`--not-headless`) vs headless (CI-shaped) before a run, then compose the command

`propose-visual-review`#

input  : an upcoming local run
output : the headed vs headless choice:
            - --not-headless: watch the browser, useful when debugging a flaky flow
            - headless (CI-shaped): faster, matches what CI does
         + the trade-off and what to watch for during a headed run
         + the composed command, handed back for the user to launch

Role#

Surface the pre-run choice; explain the trade-off.
Compose the command.
Don’t launch it — the user runs it.

12.10 — Infopreneurs, Tugan Bara, AI

Wed, 20 May 2026 00:00:00 +0000

12.10 — Infopreneurs, Tugan Bara, AI#

The ecosystem opposite to Ocarina. Not another testing framework: another cultural model. We have to name what the Holy Book fights to understand why it fights. And why AI is killing this model.

1. What is “infopreneurship”#

Definition#

Infopreneur = entrepreneur whose product is sold information: online courses, coaching programs, e-books, masterminds, “premium newsletter” subscriptions. The product isn’t physical.

Typical business model:

07.11 — CI

Wed, 20 May 2026 00:00:00 +0000

07.11 — CI#

Three workflows: main_ci.yml (fast, lint + typecheck), dev_ci.yml (same for dev/feature/fix branches), e2e.yml (manual, Redis service + Firefox).

Overview#

Workflow	Trigger	Platform	Effect
`main_ci.yml`	push/PR main	ubuntu + windows × py 3.14	`make check-coding-style` (mypy + ruff). No browser.
`dev_ci.yml`	push dev / feature/_ / fix/_	ubuntu × py 3.14	id., but Ubuntu only
`e2e.yml`	`workflow_dispatch` (manual)	ubuntu + Redis service + Firefox + geckodriver	Full run of the e2e suite. Upload `.screenshots/`, `.ocarina_logs/`, `.reports/`.

`main_ci.yml`#

name: Main branch CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

defaults:
  run:
    shell: bash

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        python-version: ["3.14"]
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with: { python-version: "3.14" }
      - uses: actions/cache@v5
        with:
          path: .venv
          key: venv-${{ runner.os }}-py3.14-${{ hashFiles('pyproject.toml') }}
      - name: Install
        run: make install-on-ci
      - name: Check coding style
        run: |
          . .venv/bin/activate
          make check-coding-style

OS matrix: ubuntu + windows — verifies Python portability.
No browser: just make check-coding-style (mypy + ruff). Fast, no Selenium / Redis / OTP.
.venv cache: reused between runs.

`dev_ci.yml`#

on:
  push:
    branches: [dev, "feature/**", "fix/**"]
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    # … identical to main_ci.yml, just Ubuntu only …

Identical to main_ci.yml but Ubuntu only (Windows only runs on main).

12.11 — The SaaS industry, ARR fraud, the con

Wed, 20 May 2026 00:00:00 +0000

12.11 — The SaaS industry, ARR fraud, the con#

Ocarina rejects SaaS. The SaaS industry is a circular ecosystem where every tool sells to every other tool, where declared revenue is inflated by convention, and where every layer of the capital chain (LP, VC, founder) deliberately maintains a plausible deniability so as to sue the others when the time comes.

1. Contemporary SaaS#

Layer	Providers (sample)	Model
Hosting & CDN	Vercel, Netlify, Cloudflare, Fly.io, Render	Subscription per project / per bandwidth
DB	Supabase, Neon, PlanetScale, Upstash, MongoDB Atlas	Subscription per compute / per GB
Auth	Clerk, Auth0, WorkOS, Stytch	Subscription per MAU
Mail	Resend, SendGrid, Postmark, Mailgun	Subscription per sent email
Analytics	PostHog, Mixpanel, Amplitude, Plausible, Vercel Analytics	Subscription per event
Error tracking	Sentry, BugSnag, Rollbar, Highlight	Subscription per event
Observability	Datadog, New Relic, Honeycomb, Grafana Cloud, Axiom	Subscription per metric volume
Feature flags	LaunchDarkly, GrowthBook, Statsig, ConfigCat	Subscription per MAU
E2E test	BrowserStack, Sauce Labs, LambdaTest, Cypress Dashboard	Subscription per run / per parallel
CI	GitHub Actions, CircleCI, Buildkite, Vercel CI	Subscription per minute
Code review	Graphite, Codeball, CodeRabbit, Sourcery	Subscription per PR / per dev
Internal comms	Slack, Linear, Notion, Figma, Loom, Pitch	Subscription per seat
Billing	Stripe, Lago, Orb, Metronome	% of processed revenue
CRM	HubSpot, Salesforce, Attio, Pipedrive	Subscription per seat
Support	Intercom, Zendesk, Plain, Help Scout	Subscription per seat + per message
AI tooling	OpenAI, Anthropic, Cursor, Vercel AI SDK, Replicate	Subscription per token + per seat

2. Cross-subscriptions#

   ┌──────────┐ pays     ┌──────────┐
   │ Vercel   │─────────>│ Stripe   │
   │          │<─────────│          │
   └──────────┘     pays └──────────┘
        │                     │
   pays │                     │ pays
        v                     v
   ┌──────────┐          ┌──────────┐
   │ Linear   │<────────>│ Notion   │
   └──────────┘   pay    └──────────┘
        │                     │
        v                     v
   ┌───────────────────────────────┐
   │ Slack, Figma, Loom, Sentry,   │
   │ Datadog, Clerk, Cursor, …     │
   │ all subscribed to all         │
   └───────────────────────────────┘

Vercel pays a subscription to Stripe (billing), Datadog (obs), Linear (planning), Figma (design), Loom (internal presentations), Slack (comms), Notion (docs).
Stripe pays a subscription to Vercel (hosting for its dashboards), Linear, Figma, Slack…
Linear pays a subscription to Vercel, Stripe, Notion, Figma, Slack.
Notion pays a subscription to Linear, Stripe, Slack, Figma.

And so on. Everyone pays everyone.

02.12 — Custom types & custom errors

Wed, 20 May 2026 00:00:00 +0000

02.12 — Custom types & custom errors#

Ocarina’s shape layer. No logic — types, aliases, exceptions, protocols. What makes the DSL typed without adding runtime logic.

`custom_types/`#

File	Contents
`effect.py`	`type Effect = Callable[[], None]` + `type Effects = tuple[Effect, ...]`
`thunk.py`	`type Thunk[T] = Callable[[], T]`
`tpom.py`	`TypeVar TPOM bound POMBase`
`supports_write.py`	`Protocol SupportsWrite[T]` (`write(s: T) -> Any`)
`built_web_driver.py`	`type BuiltWebDriver[Driver] = tuple[Driver, Effect]`
`scenario.py`	`Scenario[Driver]` (frozen dataclass)
`test_components.py`	`TestChain`, `TestSetup`, `TestTeardown`, `TestWatchers[Driver]`
`test_runner.py`	`TestRunner[Driver]` (frozen dataclass)
`oc_test.py`	`TestName`, `TestScenario[Driver]`, `TestScenarioFragment[Driver]`
`oc_test_layers.py`	`TestId`, `TestResult`, `TestSuiteResult`, `TestSuiteResults`, `TestCampaignResults`, `TestCycleResults`
`selenium/built_web_driver.py`	`BuiltSeleniumWebDriver = BuiltWebDriver[WebDriver]`
`selenium/oc_test_scenario.py`	`SeleniumTestScenario = TestScenario[WebDriver]`
`selenium/supported_browsers.py`	`type SupportedSeleniumBrowser = Literal["chrome", "firefox", "edge", "safari"]`
`selenium/web_drivers_pool.py`	`type SeleniumWebDriversPool = WebDriversPool[WebDriver]`

All these files are excluded from coverage (pyproject.toml#tool.coverage):

12.12 — DHH, Paul Graham, Haters, Mean People Fail

Wed, 20 May 2026 00:00:00 +0000

12.12 — DHH, Paul Graham, Haters, Mean People Fail#

The Holy Book quotes two big names: David Heinemeier Hansson (DHH) and Paul Graham (pg). These two authors aren’t cited at random; each embodies a precise rhetorical posture. This file explains who they are, what they wrote, and why Paul Graham’s Haters essay (and its younger sibling Mean People Fail) is the direct intellectual precedent of the “First feedbacks” chapter.

12.13 — Lambda calculus, ROP, Haskell / F# / OCaml, monads

Wed, 20 May 2026 00:00:00 +0000

12.13 — Lambda calculus, ROP, Haskell / F# / OCaml, monads#

Ocarina invents nothing on the theoretical front. It applies: from Alonzo Church’s lambda calculus (1936) to Eugenio Moggi’s (1989) and Philip Wadler’s (1992-95) monads, formalized as Railway Oriented Programming by Scott Wlaschin (2014).

1. Lambda calculus (Church, 1936)#

Definition#

Lambda calculus (λ-calculus) is a formal system invented by Alonzo Church (1903-1995) to study computability.

Primitive	Notation	Semantics
Variable	`x`, `y`, `z`	A name
Abstraction	`λx.M`	Definition of a function with parameter `x`, body `M`
Application	`M N`	Call of the function `M` on the argument `N`

Rule	Effect
α-conversion	Renaming a bound variable (`λx.x` ≡ `λy.y`)
β-reduction	Applying a function: `(λx.M) N → M[x := N]`
η-conversion	`λx.(f x) ≡ f` if `x` not free in `f`

Why it’s foundational#

1936: Church proves λ-calculus is Turing-complete (Turing publishes his machine in 1937). Church-Turing thesis: anything mechanically computable can be expressed in λ-calculus.
Alan Turing was Church’s doctoral student at Princeton (PhD, 1938).
λ-calculus is simpler than the Turing machine: only 3 constructions. Everything else — integers, booleans, data structures — is encoded with those 3 bricks (Church encoding).

Typed lambda calculus (Church, 1940)#

Church added types in 1940 (simply typed lambda calculus, STLC) to forbid self-application paradoxes (λx.x x). Each variable has a type, and function application is only allowed if types match.

12.14 — AI, and how Ocarina applies it for real

Wed, 20 May 2026 00:00:00 +0000

12.14 — AI, and how Ocarina applies it for real#

“AI-powered” became a totally idiotic marketing slogan in 2023-2026: 99% of products claiming it bolt a chat.completions endpoint onto an existing product. Ocarina proposes, on the contrary, a software infrastructure designed so an AI can contribute like a senior developer. ocarina-with-ai-example is the proof by example.

1. What AI is today#

Layer	Example	Appearance date
Statistical learning	Regression, k-means, decision trees	1960s-1990s
Deep learning	CNN (vision), RNN/LSTM (text)	2012 (AlexNet — mainstream adoption)
Transformer-based foundation models	GPT, Claude, Gemini, Llama	2017 (paper), 2018 (BERT), 2022 (ChatGPT)
Agentic workflows	AutoGPT, LangChain, Claude Code, Cursor agents	2023+

Note: CNNs were invented by Yann LeCun as early as 1989 (MNIST). AlexNet (Krizhevsky, Sutskever, Hinton, Toronto, 2012) was the industrial breakthrough. LeCun, Hinton, and Bengio share the 2018 Turing Award for their foundational contributions to deep learning.

12.15 — Typing, ISTQB, Reinforcement Learning, probes: why AI works in Ocarina

Wed, 20 May 2026 00:00:00 +0000

12.15 — Typing, ISTQB, Reinforcement Learning, probes: why AI works in Ocarina#

Why so much obsession over strict typing, formalizing every interface, alignment on ISTQB, refusing to execute an assertion without having observed? The mechanism is borrowed from Reinforcement Learning: an agent only progresses under constraint + reward signal.

1. A naked LLM is just a bad collaborator#

An LLM without a structured environment is:

Optimistic — it assumes its code works.
Persuasive — its output is convincing even when wrong.
Memoryless — it forgets conventions between sessions.
Feedbackless — it has no way to know it was wrong.
Loves what it deems “most likely” — it drifts toward popular patterns, not correct ones.

Without an environment, an LLM is an over-confident junior dev producing code that looks right, breaks in prod, and learns nothing from the failure.

12.16 — The underground internet of 1995-2010: forums, tools, banalization of cruelty

Wed, 20 May 2026 00:00:00 +0000

12.16 — The underground internet of 1995-2010: forums, tools, banalization of cruelty#

To understand the rage running through Ocarina’s Holy Book, you have to understand what the internet really was before Facebook (2006-2008), before Cloudflare became the gatekeeper (2010+), before moderation was taken seriously. It was a Wild West where state-level capabilities developed in teenagers’ bedrooms, where an adversary’s privacy could be demolished in 48 hours, and where classical legal recourse was inoperative. This page describes the mechanics, without complacency, without heroization.

12.17 — The survivor's psyche: "enemies", "narcissism", "hell", "survival", and how it bubbles up into the code

Wed, 20 May 2026 00:00:00 +0000

12.17 — The survivor’s psyche: “enemies”, “narcissism”, “hell”, “survival”, and how it bubbles up into the code#

Ocarina’s Holy Book author uses strong words: enemies, narcissism, hell on earth, survival. These words aren’t stylistic flourishes. They’re the precise descriptors of an experience lived by a whole cohort that went through the 2000s underground internet described in 16-underground-internet-2000s.md. This page explains why these words are accurate, what this lived experience produces on the psyche, and how these psychological adaptations imprint deeply into the way one programs, architects, always stays up to date.

12.18 — "Villains but not Monsters", DEF CON, "live as a white hat or die as a black hat", and Ocarina's ideology

Wed, 20 May 2026 00:00:00 +0000

12.18 — "Villains but not Monsters", DEF CON, “live as a white hat or die as a black hat”, and Ocarina’s ideology#

Ocarina is neither an aesthetic whim nor an out-of-the-blue UFO. It’s the technical expression of a coherent ideology inherited from the hacker movement: the Villain, but not a monster ethic, the tribal culture of the conferences (DEF CON foremost), and YTCracker’s stage motto: “live as a white hat, or die as a black hat”.

12.19 — It's over

Sun, 31 May 2026 00:00:00 +0000

12.19 — It’s over#

I don’t write code that “implements specs.”
I write code with a soul.
The real thing, made by someone who gives a damn. You have any idea what that means? While you look down your nose at us, while you call us autistic?

We’re not asking for anything. Just respect, and the room to do our work like normal people.
The state of this industry is exhausting.

Ocarina — manual

00.01 — Ecosystem cartography

00.01 — Ecosystem cartography#

The big picture#

Responsibilities#

Three licenses#

Deliberate friction between repos#

01.01 — Flipping the problem

01.01 — Flipping the problem#

The observation#

02.01 — Ocarina's technical identity

02.01 — Ocarina’s technical identity#

pyproject.toml#

dev dependencies#

mypy.ini#

pyproject.toml#tool.ruff#

pyproject.toml#tool.pytest.ini_options#

pyproject.toml#tool.coverage#

02.03.01 — The Result[T] type

02.03.01 — The Result[T] type#

Code#

Six design decisions, dissected#

1. _BaseResult as a common parent#

02.04.01 — The validate → assert_that → execute → raise_if_invalid flow

02.04.01 — The validate → assert_that → execute → raise_if_invalid flow#

The state machine#

Diagram#

assert_that loop#

02.05.01 — Test[Driver]

02.05.01 — Test[Driver]#

Signature#

1. @final#

02.10.01 — WebDriversPool[Driver]

02.10.01 — WebDriversPool[Driver]#

Constructor#

acquire()#

1. No reuse#

02.11.01 — CliBuilder + CliArg + _SilentArgumentParser

02.11.01 — CliBuilder + CliArg + _SilentArgumentParser#

_SilentArgumentParser#

03.01 — Effect, Thunk[T], Result[T]

03.01 — Effect, Thunk[T], Result[T]#

Triplet#

Effect vs Thunk distinction#

04.01 — From the outside like a user strategy

04.01 — "From the outside like a user" strategy#

tests/scenarios/conftest.py#

FakeDriver#

05.01 — Igoristan stack

05.01 — Igoristan stack#

package.json#

devDependencies#

engines#

06.01 — Vercel Edge stack

06.01 — Vercel Edge stack#

package.json#

07.01 — Tree

07.01 — Tree#

Folder semantics#

lib/ vs pages/#

08.01 — Code: 99% Claude, 1% Igor, intelligence: 50-50

08.01 — Code: 99% Claude, 1% Igor, intelligence: 50-50#

README#

A note to the reader#

09.01 — VitePress + Sugar Theme + in-house plugins stack

09.01 — VitePress + Sugar Theme + in-house plugins stack#

package.json#

docs/.vitepress/config.mts#

1. base#

09.03.01 — Review skills

09.03.01 — Review skills#

Listing (potentially non-exhaustive)#

review-dead-code#

review-report#

review-watcher-misuse#

review-comment-drift#

10.01 — Workflow summary matrix

10.01 — Workflow summary matrix#

Recap#

Composite action#

`pyproject.toml`#

`dev` dependencies#

`mypy.ini`#

`pyproject.toml#tool.ruff`#

`pyproject.toml#tool.pytest.ini_options`#

`pyproject.toml#tool.coverage`#

02.03.01 — The `Result[T]` type#

1. `_BaseResult` as a common parent#

02.04.01 — The `validate → assert_that → execute → raise_if_invalid` flow#

`assert_that` loop#

02.05.01 — `Test[Driver]`#

1. `@final`#

02.10.01 — `WebDriversPool[Driver]`#

`acquire()`#

02.11.01 — `CliBuilder` + `CliArg` + `_SilentArgumentParser`#

`_SilentArgumentParser`#

03.01 — `Effect`, `Thunk[T]`, `Result[T]`#

`tests/scenarios/conftest.py`#

`FakeDriver`#

`package.json`#

`devDependencies`#

`engines`#

`package.json`#

`lib/` vs `pages/`#

`package.json`#

`docs/.vitepress/config.mts`#

1. `base`#

`review-dead-code`#

`review-report`#

`review-watcher-misuse`#

`review-comment-drift`#

02.02 — The `ocarina` module tree#

The types `Action`, `FailureHandler`, `SuccHandler`#

`is_email`#

02.05.02 — `TestExecutor[Driver]`#

`ExecutionOutcome`#

`execute`#

02.10.02 — `DriverBuilder[Driver]`#

02.11.02 — `CliStore[TKeys]` + `_CliField[T]` + `phantom_validate`#

`_CliField[T]` — write-once field#

1. `_Unset` sentinel#

04.02 — Cram tests (`prysk`)#

`.t` file#

`src/config/routes.ts`#

06.02 — `GET /api/otp`#