Skip to content

Commit 2d271e2

Browse files
tanush5800claude
tanush5800
and
claude
committed
Merge origin/main into step3-manifest
Resolve 12 conflicted files. main is canonical for the tested provenance core (abi/mod.rs hash impl via #88/#46/#103, tier1/provenance.rs, codegen/query.rs), CLI plumbing (main.rs: LONG_VERSION/build.rs, doctor/gc/tier1, honest Start refusal #46, json status), and the render_manifest_template design (manifest/mod.rs — superset with retention/sidecar/version-from-Default + no-drift test). PR (HEAD) side kept for the internally-consistent V-L2-tagged Tier-2 overlay DDL (codegen/overlay.rs — superset retaining #41/#42 guarantees) and the on_off-uniform status print. Doc/test comments aligned to main. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2 parents 36fe7ee + bd84283 commit 2d271e2

36 files changed

Lines changed: 5434 additions & 702 deletions

‎.github/workflows/release.yml‎

Lines changed: 77 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -16,28 +16,79 @@ permissions:
1616

1717
jobs:
1818
build:
19-
name: Build Artifacts
20-
runs-on: ubuntu-latest
19+
name: Build (${{ matrix.target }})
20+
runs-on: ${{ matrix.runner }}
2121
permissions:
2222
contents: read
23+
strategy:
24+
fail-fast: false
25+
matrix:
26+
include:
27+
- target: x86_64-unknown-linux-gnu
28+
runner: ubuntu-latest
29+
archive_ext: tar.gz
30+
bin_ext: ''
31+
- target: aarch64-unknown-linux-gnu
32+
runner: ubuntu-latest
33+
archive_ext: tar.gz
34+
bin_ext: ''
35+
use_cross: true
36+
- target: aarch64-apple-darwin
37+
runner: macos-latest
38+
archive_ext: tar.gz
39+
bin_ext: ''
40+
- target: x86_64-pc-windows-msvc
41+
runner: windows-latest
42+
archive_ext: zip
43+
bin_ext: '.exe'
2344
steps:
2445
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
2546

26-
- name: Build
47+
- name: Install Rust toolchain
48+
uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # pinned
49+
with:
50+
toolchain: stable
51+
targets: ${{ matrix.target }}
52+
53+
- name: Install cross (linux-aarch64 only)
54+
if: matrix.use_cross
55+
run: cargo install cross --locked --version '~0.2'
56+
57+
- name: Build release binary
58+
shell: bash
59+
run: |
60+
if [ "${{ matrix.use_cross }}" = "true" ]; then
61+
cross build --release --target "${{ matrix.target }}"
62+
else
63+
cargo build --release --target "${{ matrix.target }}"
64+
fi
65+
66+
- name: Package archive
67+
shell: bash
2768
run: |
28-
echo "Build your artifacts here"
29-
# TODO: Replace with your build commands
30-
# Examples:
31-
# cargo build --release
32-
# zig build -Doptimize=ReleaseFast
33-
# gleam build
34-
# mix release
35-
36-
# TODO: Upload build artifacts if needed
37-
# - uses: actions/upload-artifact@v4
38-
# with:
39-
# name: release-artifacts
40-
# path: target/release/
69+
BIN="target/${{ matrix.target }}/release/verisimiser${{ matrix.bin_ext }}"
70+
STAGE="verisimiser-${GITHUB_REF_NAME}-${{ matrix.target }}"
71+
mkdir -p "$STAGE"
72+
cp "$BIN" "$STAGE/"
73+
cp LICENSE "$STAGE/" || true
74+
cp README.adoc "$STAGE/" || true
75+
if [ "${{ matrix.archive_ext }}" = "zip" ]; then
76+
7z a "$STAGE.zip" "$STAGE"
77+
echo "ARTIFACT=$STAGE.zip" >> "$GITHUB_ENV"
78+
else
79+
tar -czf "$STAGE.tar.gz" "$STAGE"
80+
echo "ARTIFACT=$STAGE.tar.gz" >> "$GITHUB_ENV"
81+
fi
82+
( cd . && sha256sum "$ARTIFACT" 2>/dev/null || shasum -a 256 "$ARTIFACT" ) > "$ARTIFACT.sha256"
83+
84+
- name: Upload build artifacts
85+
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
86+
with:
87+
name: release-${{ matrix.target }}
88+
path: |
89+
${{ env.ARTIFACT }}
90+
${{ env.ARTIFACT }}.sha256
91+
retention-days: 7
4192

4293
changelog:
4394
name: Generate Changelog
@@ -93,11 +144,12 @@ jobs:
93144
steps:
94145
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
95146

96-
# TODO: Download build artifacts if uploading to the release
97-
# - uses: actions/download-artifact@v4
98-
# with:
99-
# name: release-artifacts
100-
# path: artifacts/
147+
- name: Download all build artifacts
148+
uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
149+
with:
150+
path: artifacts
151+
pattern: release-*
152+
merge-multiple: true
101153

102154
- name: Create GitHub Release
103155
uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2
@@ -106,9 +158,10 @@ jobs:
106158
draft: false
107159
prerelease: ${{ contains(github.ref_name, '-rc') || contains(github.ref_name, '-beta') || contains(github.ref_name, '-alpha') }}
108160
generate_release_notes: false
109-
# TODO: Add artifact files to the release
110-
# files: |
111-
# artifacts/*
161+
files: |
162+
artifacts/*.tar.gz
163+
artifacts/*.zip
164+
artifacts/*.sha256
112165
env:
113166
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
114167

‎.github/workflows/rust-ci.yml‎

Lines changed: 29 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,16 @@
11
# SPDX-License-Identifier: PMPL-1.0-or-later
2-
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3-
#
4-
# rust-ci.yml — Cargo build, test, clippy, and fmt for Rust projects.
5-
# Only runs if Cargo.toml exists in the repo root.
2+
# Rust CI - cargo check + clippy + fmt + test on stable and MSRV
63
name: Rust CI
74

85
on:
96
pull_request:
10-
branches: ['**']
117
push:
12-
branches: [main, master]
8+
branches:
9+
- main
10+
11+
concurrency:
12+
group: rust-ci-${{ github.ref }}
13+
cancel-in-progress: true
1314

1415
concurrency:
1516
group: rust-ci-${{ github.ref }}
@@ -20,54 +21,36 @@ permissions:
2021

2122
jobs:
2223
check:
23-
name: Cargo check + clippy + fmt
24+
name: cargo check (stable)
2425
runs-on: ubuntu-latest
25-
if: hashFiles('Cargo.toml') != ''
26-
2726
steps:
28-
- name: Checkout repository
29-
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
30-
31-
- name: Install Rust toolchain
32-
uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # stable
27+
- uses: actions/checkout@v4
28+
- uses: dtolnay/rust-toolchain@stable
3329
with:
3430
components: clippy, rustfmt
35-
36-
- name: Cache cargo registry and build
37-
uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
38-
39-
- name: Cargo check
40-
run: cargo check --all-targets 2>&1
41-
42-
- name: Cargo fmt
31+
- uses: Swatinem/rust-cache@v2
32+
- name: cargo fmt
4333
run: cargo fmt --all -- --check
44-
45-
- name: Cargo clippy
34+
- name: cargo clippy
4635
run: cargo clippy --all-targets -- -D warnings
4736

4837
test:
49-
name: Cargo test
38+
name: cargo test (${{ matrix.rust }})
5039
runs-on: ubuntu-latest
5140
needs: check
52-
if: hashFiles('Cargo.toml') != ''
53-
41+
strategy:
42+
fail-fast: false
43+
matrix:
44+
rust:
45+
- "1.85"
46+
- "stable"
5447
steps:
55-
- name: Checkout repository
56-
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
57-
58-
- name: Install Rust toolchain
59-
uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # stable
60-
61-
- name: Cache cargo registry and build
62-
uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
63-
64-
- name: Run tests
65-
run: cargo test --all-targets
66-
67-
- name: Write summary
68-
if: always()
69-
run: |
70-
echo "## Rust CI Results" >> "$GITHUB_STEP_SUMMARY"
71-
echo "" >> "$GITHUB_STEP_SUMMARY"
72-
echo "- **cargo check**: passed" >> "$GITHUB_STEP_SUMMARY"
73-
echo "- **cargo test**: completed" >> "$GITHUB_STEP_SUMMARY"
48+
- uses: actions/checkout@v4
49+
- uses: dtolnay/rust-toolchain@master
50+
with:
51+
toolchain: ${{ matrix.rust }}
52+
- uses: Swatinem/rust-cache@v2
53+
with:
54+
key: ${{ matrix.rust }}
55+
- name: cargo test
56+
run: cargo test --all-targets --no-fail-fast

‎CONTRIBUTING-DEV.adoc‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
= Contributing — Developer Guide
4+
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
5+
:toc: left
6+
:toclevels: 3
7+
:icons: font
8+
:source-highlighter: rouge
9+
10+
This guide is for contributors making *code changes* to verisimiser. For
11+
repository-wide RSR conventions (commit signing, file layout, contractiles)
12+
see `.github/CONTRIBUTING.md`.
13+
14+
Three common contribution shapes get a checklist each:
15+
16+
* Adding a new database backend
17+
* Adding a new drift category
18+
* Adding a new Tier 2 overlay
19+
20+
== Clone, build, test
21+
22+
[source,bash]
23+
----
24+
git clone git@github.com:hyperpolymath/verisimiser.git
25+
cd verisimiser
26+
cargo build
27+
cargo test --lib --bins
28+
cargo clippy --all-targets -- -D warnings
29+
----
30+
31+
The full `cargo test` runs integration tests under `tests/`. On Windows those
32+
hit a TOML path-escape issue and fail spuriously; CI is the source of truth.
33+
34+
The `Justfile` lists shorthand recipes for the common loops (`just test`,
35+
`just quality`, etc.). New Justfile recipes are only added once their
36+
underlying command works — see `docs/decisions/0002-no-aspirational-justfile-recipes.adoc`.
37+
38+
== Adding a database backend
39+
40+
Adding a backend (say, MySQL) means making the entire codegen + interception
41+
pipeline aware of it. Checklist:
42+
43+
[%interactive]
44+
* [ ] Add a variant to `enum DatabaseBackend` in `src/abi/mod.rs`.
45+
* [ ] Update `DatabaseBackend::from_str` to recognise the new name plus
46+
common aliases.
47+
* [ ] Update `DatabaseBackend::as_str` (and any `Display` impl) for the
48+
new variant.
49+
* [ ] Decide the *interception strategy* (binlog CDC, change streams,
50+
WAL monitoring, application middleware …) and document it on the
51+
enum variant doc comment.
52+
* [ ] Add the dialect to `src/codegen/query.rs::build_entity_id_expr`
53+
so the no-PK fallback row identifier is correct (e.g. SQLite uses
54+
`rowid`, Postgres uses `ctid`).
55+
* [ ] Add a dialect branch to any other backend-aware site in
56+
`src/codegen/` — search for `DatabaseBackend::` usages.
57+
* [ ] If the backend needs a separate sidecar dialect, extend
58+
`src/codegen/overlay.rs` to emit the right `CREATE TABLE` syntax.
59+
* [ ] Add a unit test in `src/codegen/query.rs::tests` covering the new
60+
variant for at least one interceptor type.
61+
* [ ] Update `Cargo.toml` only if the backend needs a new connector
62+
crate (e.g. `mysql_async`). Prefer interception via the database's
63+
replication interface; pull in connector crates only as a fallback.
64+
* [ ] If the backend belongs in the published interception list, add it
65+
to `README.adoc` under *Interception methods*. Otherwise leave it
66+
in `ROADMAP.adoc`.
67+
68+
== Adding a drift category
69+
70+
The drift system is V-L1-E (see #48 for the eight-category ADR). Each
71+
category is an isolated detector with input type, distance function, and
72+
threshold.
73+
74+
[%interactive]
75+
* [ ] Open an ADR in `docs/decisions/` documenting the category's input
76+
type, distance function, and default threshold.
77+
* [ ] Add a variant to `DriftCategory` in `src/tier1/drift.rs`.
78+
* [ ] Implement a `measure(prior, current) -> f64` function returning a
79+
distance in `[0.0, 1.0]`.
80+
* [ ] Wire the measurement into the `DriftReport` aggregator.
81+
* [ ] Add unit tests for: identical inputs → 0.0; maximally different
82+
inputs → 1.0; threshold-edge cases.
83+
* [ ] Update `docs/architecture/THREAT-MODEL.adoc` if the category has
84+
adversarial implications.
85+
86+
== Adding a Tier 2 overlay
87+
88+
Tier 2 overlays require additional storage alongside the target database
89+
(graph, vector, tensor, semantic, …). New overlays are not the same as
90+
new backends.
91+
92+
[%interactive]
93+
* [ ] Add a boolean field to `Tier2Config` in `src/manifest/mod.rs` (and
94+
its `Default` impl) for the manifest toggle.
95+
* [ ] Decide the sidecar storage technology (pure Rust, HNSW, ndarray, …)
96+
and document it on the `Tier2Config` field doc comment.
97+
* [ ] Add overlay DDL emission in `src/codegen/overlay.rs` behind the new
98+
flag.
99+
* [ ] Add an interceptor in `src/codegen/query.rs` that routes the right
100+
queries to the overlay.
101+
* [ ] Add a round-trip test in `src/codegen/overlay.rs::tests` covering
102+
the flag both on and off.
103+
* [ ] Update `README.adoc`'s *Octad: Eight Modalities* table to reflect
104+
the new overlay's tier and storage.
105+
106+
== Style notes
107+
108+
* Treat `cargo clippy --all-targets -- -D warnings` as part of `cargo
109+
build`. The crate has no blanket `#![allow(...)]` blocks
110+
(`docs/decisions/0001` and 0002 keep the surface clean).
111+
* Public items used as the library API should be `pub`; binary-only
112+
helpers stay private.
113+
* All commits are SSH-signed (see `.github/CONTRIBUTING.md`).
114+
* PRs target `main`. Auto-merge with `--squash` is the norm.

0 commit comments

Comments
 (0)