Skip to content

CONTRIBUTING-DEV.adoc

Latest commit

 

History

History
163 lines (137 loc) · 7.16 KB

CONTRIBUTING-DEV.adoc

File metadata and controls

163 lines (137 loc) · 7.16 KB
Raw

Contributing — Developer Guide

Table of Contents

This guide is for contributors making code changes to verisimiser. For repository-wide RSR conventions (commit signing, file layout, contractiles) see .github/CONTRIBUTING.md.

Three common contribution shapes get a checklist each:

  • Adding a new database backend

  • Adding a new drift category

  • Adding a new Tier 2 overlay

Clone, build, test

git clone git@github.com:hyperpolymath/verisimiser.git
cd verisimiser
cargo build
cargo test --lib --bins
cargo clippy --all-targets -- -D warnings

The full cargo test runs integration tests under tests/. On Windows those hit a TOML path-escape issue and fail spuriously; CI is the source of truth.

The Justfile lists shorthand recipes for the common loops (just test, just quality, etc.). New Justfile recipes are only added once their underlying command works — see docs/decisions/0002-no-aspirational-justfile-recipes.adoc.

Adding a database backend

Adding a backend (say, MySQL) means making the entire codegen + interception pipeline aware of it. Checklist:

  • Add a variant to enum DatabaseBackend in src/abi/mod.rs.

  • Update DatabaseBackend::from_str to recognise the new name plus common aliases.

  • Update DatabaseBackend::as_str (and any Display impl) for the new variant.

  • Decide the interception strategy (binlog CDC, change streams, WAL monitoring, application middleware …) and document it on the enum variant doc comment.

  • Add the dialect to src/codegen/query.rs::build_entity_id_expr so the no-PK fallback row identifier is correct (e.g. SQLite uses rowid, Postgres uses ctid).

  • Add a dialect branch to any other backend-aware site in src/codegen/ — search for DatabaseBackend:: usages.

  • If the backend needs a separate sidecar dialect, extend src/codegen/overlay.rs to emit the right CREATE TABLE syntax.

  • Add a unit test in src/codegen/query.rs::tests covering the new variant for at least one interceptor type.

  • Update Cargo.toml only if the backend needs a new connector crate (e.g. mysql_async). Prefer interception via the database’s replication interface; pull in connector crates only as a fallback.

  • If the backend belongs in the published interception list, add it to README.adoc under Interception methods. Otherwise leave it in ROADMAP.adoc.

Adding a drift category

The drift system is V-L1-E (see #48 for the eight-category ADR). Each category is an isolated detector with input type, distance function, and threshold.

  • Open an ADR in docs/decisions/ documenting the category’s input type, distance function, and default threshold.

  • Add a variant to DriftCategory in src/tier1/drift.rs.

  • Implement a measure(prior, current) → f64 function returning a distance in [0.0, 1.0].

  • Wire the measurement into the DriftReport aggregator.

  • Add unit tests for: identical inputs → 0.0; maximally different inputs → 1.0; threshold-edge cases.

  • Update docs/architecture/THREAT-MODEL.adoc if the category has adversarial implications.

Adding a Tier 2 overlay

Tier 2 overlays require additional storage alongside the target database. The overlay modality set is fixed at six (graph, vector, tensor, semantic, document, spatial) per ADR-0014; a seventh is an ontology change, not a config edit. New overlays are not the same as new backends.

  • Add a boolean field to Tier2Config in src/manifest/mod.rs (and its Default impl) for the manifest toggle.

  • Decide the sidecar storage technology (pure Rust, HNSW, ndarray, …) and document it on the Tier2Config field doc comment.

  • Add overlay DDL emission in src/codegen/overlay.rs behind the new flag.

  • Add an interceptor in src/codegen/query.rs that routes the right queries to the overlay.

  • Add a round-trip test in src/codegen/overlay.rs::tests covering the flag both on and off.

  • Update the README.adoc Tier 2 section (overlay modality set, storage, status) and the vocabulary table in the README (anchor octad-vocabulary). The README no longer has an "Octad: Eight Modalities" table. Note that a new overlay changes the set’s membership and so needs an ADR, not just a README edit (ADR-0014 §14.3).

Commands in docs must exist

Documentation is treated as an interface: if a guide tells someone to run a command, that command has to work. The RSR templates this repo started from referenced recipes from other projects, so several guides shipped instructions that failed with Justfile does not contain recipe.

  • Only reference recipes that the Justfile (or an imported *.just) defines. just --list is authoritative.

  • just doc-recipes runs scripts/check-doc-recipes.sh, which fails if any .adoc code block mentions an undefined recipe. Run it after editing docs.

  • Do not add a recipe just to satisfy a doc. ADR-0002 removed aspirational recipes that wrapped things which did not exist; the fix direction is to correct the docs, not to invent the recipe.

Known non-recipes, with the real alternative:

Mentioned in old docs Actually

just setup, just setup-dev

cargo fetch / just deps (./setup.sh falls back to just doctor)

just check-error-codes

No error-code catalogue exists in this repo

just e2e

just test (tests/ holds the integration + e2e suite)

just panic-scan

just assail

just llm-context

read 0-AI-MANIFEST.a2ml and .claude/CLAUDE.md

just build-release

just build

just install --prefix=…

cargo install --path . --root <prefix>

just stapeln-*, just uninstall, just init

Not present

Template artifacts that are sync-managed from hyperpolymath/standards (docs/RSR_OUTLINE.adoc, container/, .machine_readable/*) still describe the template’s own recipes; just doc-recipes reports and skips the one it scans rather than rewriting synced content.

Style notes

  • Vocabulary (ADR-0014): unqualified Octad means VeriSimiser’s fixed eight-concern model; write VeriSimDB’s Octad for the upstream eight-modality API/model. Tier 2 uses overlay modality set for the fixed six and enabled overlays for a manifest’s selection — not "modality profile". Do not rename schema, CLI, or manifest fields to match a doc change; that needs its own compatibility decision.

  • Treat cargo clippy --all-targets — -D warnings as part of cargo build. The crate has no blanket #![allow(…​)] blocks (docs/decisions/0001 and 0002 keep the surface clean).

  • Public items used as the library API should be pub; binary-only helpers stay private.

  • All commits are SSH-signed (see .github/CONTRIBUTING.md).

  • PRs target main. Auto-merge with --squash is the norm.