ci: pushes, pull requests and dispatches test the engine built from this commit's source (#163) - #506

Refs #163. This is the CI half of the issue; the release half is not touched (see "Not in this PR").

What changes

Pushes to main, pull requests and manual dispatches of test-python-bindings.yml and test-python-examples.yml now test the engine built from the commit's own source (./mvnw -pl package -am package, the full distribution), not the jars of upstream's moving snapshot image. The snapshot can carry fixes this repository's source lacks, which is what fired five strict-xfail tripwires on 2026-10-04 (#143).

• download-jars gets a mode step: the engine-from-source input is empty on push and pull request (so it means true), true by default on a dispatch, and false by default on a workflow_call. The result is a job output that the test jobs read, so the Linux Docker build, which got the jars handed over only when the input was set, follows the same switch.
• The built jars are cached with actions/cache (already pinned in the examples workflow) under engine-jars-v1-<hash>. The hash covers the root pom.xml, mvnw, .mvn, every pom.xml and every src/main tree outside bindings/, benchmarks/, e2e*/, load-tests/ and docs/. A bindings-only change restores the jars in seconds; the JDK setup and the Maven build run only on a miss.
• A dispatch with engine-from-source: false still tests the arcadedata/arcadedb:<pom version> image.
• Docs: ci-setup.md, build-architecture.md, testing.md, known-issues.md, the header of build-engine-jars.yml and the docstrings of the two tests that described the snapshot image.

Cost

No new runner type, no new matrix leg: the only addition is the Maven build in download-jars on ubuntu-24.04, on a cache miss only. The issue estimated about 3 to 4 minutes per build. Both test workflows share the key but build in parallel on a cold cache, so the first run for a new engine tree builds twice (an estimated 7 to 8 Linux runner minutes, to be read from this PR's download-jars jobs); every later run with the same engine tree is a cache hit. The repository is public, so standard runners are free; the matrix legs (including macOS) are unchanged.

Not in this PR

The release workflow is unchanged on purpose (AGENTS.md: ask before changing the release routine). It calls both test workflows without engine-from-source, which stays false there, so releases and dev tags keep taking the jars of the arcadedata/arcadedb image as before. The rest of the issue's plan needs a decision first: the class-for-class gate for stable releases, dev tags shipping the source build, and build.sh --engine-from-source.

This workflow change also crosses to the upstream bindings pull request (docs/development/upstream-bindings-pr.md): both files are shipped there, and the engine layout is the same.

Checks

• actionlint 1.7.12 on all workflows: clean.
• pre-commit on the changed files: passes.
• The live test is this PR's own run (the workflows are in their own path filter): the Choose where the engine jars come from step should print engine-from-source=true, the first run should miss the cache and build, a second push should hit it.

🤖 Generated with Claude Code