Java and Maven development¶

The repository contains one experimental Java artifact, org.meridiandb:meridiandb-core:0.1.0-SNAPSHOT. It contains immutable experimental command, query, interval, result and commit-position types in org.meridiandb.temporal. A test-only reference model executes the canonical contract histories and seeded checks alongside the embedded in-memory engine in org.meridiandb.engine. The engine is experimental and memory-only. The journal codec and local file adapter in org.meridiandb.storage.journal provide bounded append, force and replay independently of that engine. The pure immutable history codec adds exact segment bytes and content identity. The local segment adapter adds create-only file writes and verified heap readers. The manifest codec and verifier add complete-set consistency against a reconstructed journal-prefix binding. The local checkpoint store adds actual owner-journal verification, immutable generation publication and verified reopen under explicit filesystem capabilities. Local database recovery restores read-only temporal queries and request lookup from complete checkpoint history plus the journal suffix. Explicit writable modes now synchronize startup and force each new record before atomic query publication and acknowledgement. Durability conformance adds process exits, retry and canonical/seeded writable-reopen checks. Pure history compaction validates supplied checkpoint history and returns bounded exact-history replacement proposals. Local compaction publication now verifies/reuses or installs outputs and selects the next generation at the same cutoff. Lazy readers now hold independent shared cross-process protection, with explicit release/cleanup behavior. Protected physical deletion remains planned. A bounded inventory now verifies explicit retained roots and obsolete-object metadata without removal. No library is published.

Build and verify¶

Install a JDK from the Java 25 line, the baseline recorded in .java-version and compiler release in pom.xml. Select it through JAVA_HOME/PATH in your normal environment. A separately installed Maven is not required. The build decision explains this baseline.

Run from the repository root on macOS or Linux:

./mvnw -B verify

On Windows PowerShell:

.\mvnw.cmd -B verify

The wrapper downloads Maven 3.10.0 on first use, checks the distribution's pinned SHA-256, and caches it. Maven resolves pinned plugins and test dependencies from Maven Central, so a cold build needs network access. The POSIX bootstrap needs a shell, unzip and either sha256sum or shasum; it can download through curl, wget or its Java fallback. The Windows launcher uses PowerShell.

Verification compiles production/test code, runs JUnit Jupiter and produces the local target/meridiandb-core-0.1.0-SNAPSHOT.jar. Reports are under target/surefire-reports/. target/ is ignored. The artifact has no external runtime dependencies; JUnit and Jackson are test-only. The command does not install a library into a remote repository or publish a release.

To remove stale output before verifying:

./mvnw -B clean verify

To inspect the actual Maven and Java runtime selected by the wrapper:

./mvnw -version

The current 747 test invocations include 69 reclamation inventory checks, 70 reader protection/identity/cleanup checks, 55 local compaction publication/integration/process checks, 57 pure compaction checks, 55 typed query checks, 50 durable conformance checks, 49 commit preparation/initialization/publication checks, 37 local database recovery checks, 39 local checkpoint publication checks, 45 manifest codec/consistency checks, 36 local segment I/O/lifetime checks, 27 immutable segment codec checks, 29 journal codec checks, 58 local journal I/O/process/prefix checks and 71 temporal/engine checks: 18 interval boundary checks, eight type checks, ten reference/decoding checks, five canonical histories per implementation, 16 seeded histories comparing both implementations with dense snapshots, and nine engine lifecycle/concurrency checks. The memory engine and reference each execute 84 exact fixture expectations and 512 seeded new transactions. Local read recovery executes the canonical histories in three checkpoint shapes. The reference guide and engine guide explain coverage and limits. The local adapters have separate failure/reopen tests; forced local writes and atomic publication have focused checks alongside real process exits and seeded writable reopen. The journal specification documents golden bytes, corruption/truncation, exact identity and allocation-limit coverage.

Run the embedding example after verification, on either platform:

java --class-path target/classes examples/EmbeddedExample.java

This uses JDK source-file launch mode with the compiled project classes. There is no extra execution plugin or example dependency.

Project conventions¶

Use standard src/main/java and src/test/java layouts. Keep production packages under org.meridiandb; the first primitive lives in .temporal. Match test package and source names, with *Test classes discovered by Surefire. Use JUnit Jupiter, exact contract expectations and focused failure cases. The build fails when no tests are discovered. Production code compiles with --release 25, -Xlint:all and -Werror; preview features are not enabled.

Start with one JAR and introduce another module only for an actual deliverable. The group/artifact coordinates are project conventions, not a Maven Central publication or verified-namespace claim. No release repository is configured. The records and their nullable unbounded endpoints are experimental Java syntax; the logical contract remains authoritative as the type set develops. Maven loads docs/architecture/fixtures/temporal-contract-v0.json and temporal-query-v0.json as test resources under contracts/; keep those sources authoritative rather than copying their expectations. The seed corpus is src/test/resources/reference-seeds.txt. Test code/resources and their JSON parser stay outside the production JAR.

Pin build/test plugins in the POM, including the default clean/verify lifecycle and managed install/deploy/wrapper goals. Install/deploy versions are managed for predictability, without binding either goal to verification. Maven site generation is not part of this build; the documentation toolchain remains separate. project.build.outputTimestamp fixes archive timestamps for repeatable packaging from identical inputs and JDK; it is not a release date or a guarantee that every compiler patch/vendor emits identical bytes.

Research Maven versions for every Maven change¶

For Maven implementation, build or dependency changes, check the current versions of the affected pinned artifacts: Maven, wrapper components, lifecycle/test plugins and direct dependencies. Use Maven Central metadata and official project release and compatibility documentation. Record the date, coordinates, latest stable release, selected version and any compatibility/security reason for a difference. The dated table below records the current selection.

Research before selecting versions; do not substitute a remembered version or a passing cached build. Metadata latest and release can point to prereleases: the initial Maven metadata points to Maven 4 RC and several plugin 4.x betas. Check the release channel and runtime requirements. Prefer the latest stable compatible release, then pin its exact version. A prerelease needs a concrete reason and validation. Keep transitive dependencies governed by their pinned upstream artifacts unless a researched compatibility/security finding requires an explicit override; inspect the resolved graph when that contract changes. Floating LATEST, version ranges and snapshot dependencies are not the update mechanism. The project's own unreleased 0.1.0-SNAPSHOT is separate from that rule.

Artifact research checked on 2026-10-29¶

These are dated findings, not a promise that the versions remain latest. POM and wrapper properties own executable configuration. Apache's download page recommends Maven 3.10.0; Maven 4 is preview. The plugin catalog confirms the stable Maven 3 plugin lines. The JUnit guide identifies JUnit 6.1.3 and its Java 17 minimum, compatible with this Java 25 baseline. Jackson 3.2.4 decodes canonical temporal and query test fixtures. The Jackson project documents its 3.x tools.jackson packages and Java 17 baseline. Its tree model lets the adapter reject non-integral or out-of-range values before constructing a transaction. The journal codec uses JDK CRC32C and byte buffers, adding no runtime dependency. The local adapter also uses only JDK file I/O. All twelve metadata sources and official Maven/JUnit/Jackson compatibility information were rechecked for reclamation inventory on October 29 at 15:18:57 Toronto / 19:18:57 UTC; the selected versions remain unchanged. The segment and manifest codecs use standard JDK SHA-256/CRC32C and the local adapters use JDK file I/O, with no new dependency.

All selected entries are the latest stable releases found. Newer metadata entries in the Maven/plugin 4.x series are RC/beta releases, so they are not selected for the stable Maven 3 build. The Enforcer plugin was also researched but is not needed for this small foundation; javac's release setting and the wrapper define the current baseline without another verification plugin.

Wrapper provenance and updates¶

The scripts were generated with Apache Maven Wrapper Plugin 3.3.4, using its only-script distribution. Both launchers are tracked; mvnw is executable with LF endings and mvnw.cmd uses CRLF on checkout. There is no wrapper JAR to commit.

The Maven ZIP at the wrapper's distributionUrl was compared against Apache's published SHA-512. Its computed SHA-256 is pinned as distributionSha256Sum in .mvn/wrapper/maven-wrapper.properties. A fresh-bootstrap negative check also confirmed rejection of an incorrect checksum. This verifies distribution integrity; it does not claim independent signature verification of every dependency.

After researching a wrapper/runtime update, generate the scripts using fully qualified, exact plugin/version arguments. The initial reproducible generation command is:

./mvnw org.apache.maven.plugins:maven-wrapper-plugin:3.3.4:wrapper -Dmaven=3.10.0 -Dtype=only-script

Generation can rewrite wrapper properties. Verify the selected archive against Apache's official checksum, restore its exact SHA-256 pin before building, review the scripts/properties and run a fresh bootstrap plus ./mvnw -B verify. Keep the checksum when resolving missing bootstrap tools. Update POM management, research evidence and build guidance with a version change.

Continuous integration¶

Java checks runs on affected pull requests and pushes to main, with read-only repository permissions and credentials removed after checkout. Linux runs ./mvnw -B verify; Windows runs .\mvnw.cmd -B verify. Both select Temurin from .java-version, checking for the latest patch in that Java line. Action versions are pinned by commit; CI prints the actual runtime. Maven dependencies are cached by POM content. Changes to the temporal contract, journal format or canonical fixture directory also trigger Java checks, since they affect executable expectations. No Java artifact is uploaded or released by this workflow. Both platforms also run twelve examples: embedded queries, local journal, pure segment codec, local immutable files, manifest consistency, local checkpoint publication, local read recovery, forced local writes, typed temporal queries, pure history compaction, local compaction publication and reclamation inventory. The five local checkpoint/recovery/write/compaction/inventory examples report an unavailable directory open/force capability explicitly; capability-dependent real-file tests skip on that specific boundary while injected checks still run. Changes under examples/ trigger these checks.

Documentation checks and automatic Pages publication retain their own workflows. For website setup and verification, follow the documentation guide.