fix(metadata): use canonical JSON library for cross-language hash compatibility

.github/workflows/test.yml

@@ -87,9 +87,17 @@ jobs:
       - name: Verify interop fixture is up to date
         run: |
           (cd verity-core && python3 make_testfiles.py)
-          cargo run -p cryptpilot-verity -- format verity-core/testfiles --hash-output - --label env=prod --force
+          HASH=$(cargo run -q -p cryptpilot-verity -- format verity-core/testfiles --hash-output - --label env=prod --force)
           diff verity-core/testfiles/cryptpilot-verity.metadata.fb verity-go/metadata/testdata/rust.metadata.fb \
             || { echo "ERROR: interop fixture is stale. Run verity-go/metadata/gen_fixture.sh to regenerate."; exit 1; }
+          EXPECTED_HASH=$(cat verity-go/metadata/testdata/rust.metadata.fb.hash | tr -d '[:space:]')
+          if [ "$HASH" != "$EXPECTED_HASH" ]; then
+            echo "ERROR: root hash mismatch"
+            echo "  expected: $EXPECTED_HASH"
+            echo "  got:      $HASH"
+            exit 1
+          fi
+          echo "Interop fixture and root hash are up to date"
       - name: Run Go tests
         run: |
           cd verity-go

CLAUDE.md

@@ -4,6 +4,10 @@
 
 When modifying the Rust `cryptpilot-verity`, `verity-core`, or `verity-fuse` code, always evaluate whether the corresponding Go library (`verity-go/`) needs the same change. If the change affects core algorithms (hash computation, merkle tree, descriptor format) or metadata structures (FlatBuffers schema, serialization), apply the equivalent change to the Go code in the same commit.
 
+## Documentation Sync
+
+When creating or modifying features, commands, or interfaces, always evaluate whether the corresponding documentation (README.md, CLAUDE.md, or other .md files under the project) needs to be updated. If the change introduces new commands, modifies existing behavior, adds configuration options, or changes usage examples, update the relevant documentation in the same commit.
+
 ## Excluded Paths
 
 Never commit files under `docs/superpowers/` or `.claude/` to git. These are Claude session artifacts and should be kept local only. Add them to `.gitignore` if not already present.
@@ -40,6 +44,28 @@ Fix any errors or warnings reported before proceeding with the commit.
 - Run `make test` in `cryptpilot-verity/` to execute the full integration test suite
   (format, dump, verify, open/FUSE mount, tamper detection, close).
 - Run `cargo test -p verity-fuse -p verity-core` for unit tests (requires `cd verity-core && python3 make_testfiles.py` first).
+- Run Go tests: `cd verity-go && go test -race -v ./...`
+
+## Pre-Push / Pre-PR Checks
+
+Before pushing or creating a pull request, always run the relevant checks and ensure they pass.
+
+**Always run (regardless of what changed):**
+```bash
+cargo fmt --check
+cargo build        # or `make clippy` / `cargo clippy` if lints are relevant
+```
+
+**When modifying verity-related code** (`cryptpilot-verity`, `verity-core`, `verity-fuse`, or `verity-go`):
+```bash
+# Rust verity tests
+cargo test -p cryptpilot-verity -p verity-core -p verity-fuse
+
+# Go verity tests
+cd verity-go && go build ./... && go test -race -v ./...
+```
+
+For changes outside the verity subsystem, run the tests relevant to the affected packages only. If system dependencies are missing (e.g., `libcryptsetup`), the CI pipeline serves as the authoritative check, but `cargo fmt --check` must always pass locally.
 
 ## FUSE Dependency
 

Makefile

@@ -357,7 +357,6 @@ docker-build-all: docker-build
 .PHONY: check-fbs
 check-fbs:
 	@test -L verity-go/metadata/metadata.fbs || { echo "ERROR: metadata.fbs should be a symlink to Rust source"; exit 1; }
-	@test -L verity-go/metadata/metadata_hash.fbs || { echo "ERROR: metadata_hash.fbs should be a symlink to Rust source"; exit 1; }
 	@echo "FlatBuffers schemas are shared via symlink."
 
 .PHONY: go-test
@@ -372,7 +371,9 @@ check-all: clippy go-test check-fbs
 gen-interop-fixture:
 	@echo "=== Generating interop fixture ==="
 	cd verity-core && python3 make_testfiles.py
-	cargo run -p cryptpilot-verity -- format verity-core/testfiles --hash-output - --label env=prod --force
-	cp verity-core/testfiles/cryptpilot-verity.metadata.fb verity-go/metadata/testdata/rust.metadata.fb
-	@echo "Fixture updated: verity-go/metadata/testdata/rust.metadata.fb"
+	@HASH=$$(cargo run -q -p cryptpilot-verity -- format verity-core/testfiles --hash-output - --label env=prod --force); \
+	cp verity-core/testfiles/cryptpilot-verity.metadata.fb verity-go/metadata/testdata/rust.metadata.fb; \
+	echo "$$HASH" > verity-go/metadata/testdata/rust.metadata.fb.hash; \
+	echo "Fixture updated: verity-go/metadata/testdata/rust.metadata.fb"; \
+	echo "Root hash: $$HASH"
 

cryptpilot-verity/Cargo.toml

@@ -7,6 +7,7 @@ version.workspace = true
 [dependencies]
 anyhow = {workspace = true}
 base64 = {workspace = true}
+canon-json = "0.2.1"
 async-trait = {workspace = true}
 async-walkdir = {workspace = true}
 clap = {workspace = true}

cryptpilot-verity/build.rs

@@ -3,12 +3,10 @@ use std::path::Path;
 fn main() -> shadow_rs::SdResult<()> {
     shadow_rs::new()?;
 
-    // Compile FlatBuffers schemas
+    // Compile FlatBuffers schema
     let metadata_schema = Path::new("src/metadata/metadata.fbs");
-    let hash_schema = Path::new("src/metadata/metadata_hash.fbs");
 
     println!("cargo:rerun-if-changed={}", metadata_schema.display());
-    println!("cargo:rerun-if-changed={}", hash_schema.display());
 
     // Get flatc binary path from flatc crate
     let flatc_path = flatc::flatc();
@@ -17,7 +15,7 @@ fn main() -> shadow_rs::SdResult<()> {
     // First check with have good `flatc`
     flatc_cmd.check()?;
 
-    // Compile main metadata schema
+    // Compile schema
     flatc_cmd
         .run(flatc_rust::Args {
             inputs: &[metadata_schema],
@@ -26,14 +24,5 @@ fn main() -> shadow_rs::SdResult<()> {
         })
         .expect("Failed to compile metadata.fbs");
 
-    // Compile hash schema
-    flatc_cmd
-        .run(flatc_rust::Args {
-            inputs: &[hash_schema],
-            out_dir: Path::new("src/metadata/"),
-            ..Default::default()
-        })
-        .expect("Failed to compile metadata_hash.fbs");
-
     Ok(())
 }