Aquila Graph POC

A reproducible proof of concept for combining static and runtime Java facts in a provenance-preserving graph, persisting the fused snapshot, and evaluating the same read-only query before and after fusion.

The repository intentionally supports one bounded claim. It is an inspectable experiment, not a production implementation or performance benchmark. Independent reproduction, constructive criticism, counterexamples, and focused contributions are not merely welcome; they are expected parts of evaluating the claim.

Run it

Prerequisites: Bash and Docker with the plugin-style docker compose interface.

git clone https://github.com/eagle-head/aquila-graph-poc.git
cd aquila-graph-poc
./poc.sh run

The command builds the pinned container image when necessary, runs four fixed scales, independently reconstructs the analysis, prints a compact JSON result, and stores the complete local evidence below .runs/<run-id>/.

Application progress is emitted as JSON Lines on standard error. Standard output is reserved for the compact JSON result.

A successful run reports:

• four completed and semantically verified units;
• four plausible wrong results rejected by the intended oracle;
• 13 declared, 16 static, 3 observed, 2 security-modeled, and 5 derived facts;
• two matched observations, one identity-safe orphan, and one deliberately lost event;
• two read-only query rows: one before fusion and one after fusion; and
• assessment and aggregate-fact representations on one immutable base without contributor-layer collapse; and
• no architectural decision or authority effect.

Timing and resource values will vary by host and are descriptive only.

Commands

Command	Purpose
./poc.sh build	Build from immutable Python and Temurin base-image digests.
./poc.sh test	Run the behavioral contracts and a real semantic canary.
./poc.sh run	Run and independently verify the complete four-scale POC.
./poc.sh run --run-id my-run	Run with a caller-selected safe output identifier.
./poc.sh check --run-id my-run	Reconstruct and compare an existing run.

poc.sh is the supported entry point. It validates caller identity, records source revision and worktree state, prepares the create-only run root, and then invokes Docker Compose. Calling Compose directly bypasses those launcher obligations and is not an equivalent execution path.

Reproducibility model

• Python 3.13.14 and Eclipse Temurin 25.0.3+9 come from Docker Official Images pinned by multi-architecture OCI digest.
• External networking is requested as disabled; the runtime manifest observes only the loopback interface and a read-only application filesystem on every public run.
• The process runs as a non-root caller with all Linux capabilities dropped and no-new-privileges enabled; effective IDs, groups, capabilities, and privilege state are observed and must satisfy that contract.
• Every source input, runtime executable, selected JDK tree, raw record, and derived result is bound by SHA-256 inventories.
• The analyzer is run once to create results and again in check-only mode to reconstruct them independently.
• Containers stabilize user-space tools, not the host kernel, CPU architecture, scheduling, or container runtime. Performance observations therefore remain non-gateable.

These choices follow the official Docker guidance on build best practices and use the official Python and Eclipse Temurin images.

Repository structure

ARCHITECTURE.md     Component boundaries, evidence flow, and trust model
CHANGELOG.md        Repository-level PoC change history
CITATION.cff        Machine-readable software citation metadata
COMPATIBILITY.md    Required interfaces and evidence-backed environments
TROUBLESHOOTING.md  Public-command diagnosis and safe run cleanup
.vitepress/         Documentation presentation and navigation only
docs/               Documentation checks and diagram assets
poc/                Executable fixture, contract, oracles, runner, and tests
evidence/           Accepted source narrative and compact historical receipt
.runs/              Ignored, reproducible output generated by local executions
.github/workflows/  Continuous reproduction on GitHub Actions
docker-compose.yml  Restricted one-shot execution environment
Dockerfile          Pinned multi-stage image definition
poc.sh              Bash entry point for build, test, run, and check

The exact claim and nonclaims are in poc/contract.md. The implementation boundaries and trust model are in ARCHITECTURE.md, and migration lineage is recorded in poc/PROVENANCE.md. Security scope and reporting guidance are in SECURITY.md. Operational diagnosis is in TROUBLESHOOTING.md, and retained files are documented in poc/ARTIFACTS.md. Tested and untested environment boundaries are in COMPATIBILITY.md, and repository changes are recorded in CHANGELOG.md.

Documentation site

The same canonical Markdown is configured for publication through VitePress at eagle-head.github.io/aquila-graph-poc after GitHub Pages is enabled. The site is a presentation layer; it does not define the contract, participate in a run, or authenticate evidence.

Node.js and npm are required only to build or preview the documentation. With a Node version accepted by package.json:

npm ci --ignore-scripts
npm run docs:check
npm run docs:dev

The first two commands reproduce the locked documentation toolchain and verify the production site. The last command starts a local authoring server. See the docs guide for source ownership, review rules, and publication boundaries.

Review and contributions

Criticism, independent reproductions, counterexamples, and design suggestions are highly encouraged. Start with CONTRIBUTING.md, and attach the public results/output.json, source inventory digest, platform, and Docker version when reporting a divergent result. Follow SECURITY.md before reporting a potential security issue.

Citation

If this proof of concept is used in research or another published work, cite it using the machine-readable metadata in CITATION.cff.

License

Copyright 2026 Eduardo Kohn.

Except where otherwise noted, project-authored content in this repository is licensed under the Apache License 2.0. The SPDX identifier is Apache-2.0.

Third-party base images, runtimes, and tools remain subject to their own license terms.