feat: typed verification codes + shared hash helpers

[Fieldnote-Echo]

Wave U2 of the OrdinalDB post-mortem hardening (post-mortem F2 upstream half + F14). Stacked on #287 (feat/deterministic-manifest) — merge that first; GitHub will retarget this to main.

• Every verification issue code is now a named pub const in a codes module — zero bare literals at emit sites; internal string-compares switched to consts.
• #[non_exhaustive] pub enum VerificationCode + ReportIssue::classification() so downstream security code (ordinaldb IntegrityError mapping) branches on typed values, never strings. Serialized report JSON is byte-stable (regression-tested).
• Structured mismatch detail (expected/actual sha256 + sizes) exposed for lossless downstream error construction.
• sha256_bytes + bounded sha256_reader sharing sha256_file_bounded's EINTR/bounded core; private sqlite duplicate deduped onto the pub fn (F14 — brief-06 reimplemented this by hand, the drift risk this closes).

Adversarial 3-lens review: clean (low-only findings). Tests: 95-108 passed across feature combos; clippy/fmt clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BQ1JzAocstWiqtCF5J2V7K

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[qodo-code-review]

PR Summary by Qodo

Add typed verification codes and shared SHA-256 helpers

✨ Enhancement 🧪 Tests 🕐 40+ Minutes

AI Description

• Centralize all verification issue codes as codes::* constants to prevent silent drift.
• Add typed VerificationCode classification and structured mismatch details for downstream
 security handling.
• Introduce shared SHA-256 helpers (sha256_bytes, bounded sha256_reader) and regression tests
 for stability.

Diagram

graph TD
  E[("SQLite cache")] --> A["Manifest verifier"] --> C["ReportIssue JSON"]
  A --> B["Issue codes"]
  A --> D["Hash helpers"]
  T["Regression tests"] --> A --> C
  E --> D

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Macro-generated code registry

• ➕ Single source of truth could generate codes::*, the enum mapping, and tests
• ➕ Reduces risk of missing new codes in classification or value-lock tests
• ➖ More metaprogramming complexity and less straightforward code search/grep
• ➖ Harder to review/maintain without careful macro hygiene

2. Derive-based string↔enum mapping (e.g., `strum`)

• ➕ Less hand-written match logic for classification()
• ➕ Can support future bidirectional conversions and display formatting
• ➖ Adds dependency surface area for a security-adjacent mapping
• ➖ Still requires a strategy for stable external string values

3. Keep string codes, add typed layer only downstream

• ➕ No API additions in ordvec-manifest
• ➕ Avoids introducing optional structured fields in report issues
• ➖ Downstream remains exposed to typos/drift in raw strings
• ➖ Doesn’t address emit-site literal reintroduction risk

Recommendation: The PR’s approach is the right trade: centralizing all codes as pub const values plus adding a small, explicitly-scoped VerificationCode classification improves downstream safety without changing the wire format (validated via byte-stability tests). If drift between consts and classification becomes a recurring maintenance issue, consider a macro-generated registry later, but the current explicit mapping is easiest to audit in a hardening context.

Files changed (5) +1281 / -301

Enhancement (1) +803 / -273

lib.rsCentralize issue codes, add typed classification, structured mismatch detail, and hash helpers +803/-273

Centralize issue codes, add typed classification, structured mismatch detail, and hash helpers

• Replaces all emitted issue-code string literals with 'codes::*' constants, including context/field-specific code bundles for path, metric, and row-id validation. Adds '#[non_exhaustive] VerificationCode' plus 'ReportIssue::classification()' for typed downstream branching, and extends 'ReportIssue' with optional artifact/expected/actual SHA-256 and size details while preserving legacy JSON output via 'skip_serializing_if'. Introduces shared hashing helpers ('sha256_bytes', bounded 'sha256_reader') by extracting the bounded/EINTR-safe core from 'sha256_file_bounded'.

ordvec-manifest/src/lib.rs

Refactor (1) +20 / -26

sqlite.rsDeduplicate hashing and adopt shared 'codes::*' constants in sqlite cache flow +20/-26

Deduplicate hashing and adopt shared 'codes::*' constants in sqlite cache flow

• Switches sqlite activation/caching issue codes to the shared 'codes::*' constants and updates bounded-hash calls accordingly. Removes the local 'sha256_bytes' implementation in favor of the public helper and adjusts cache-key hashing to use the '.sha256' string from 'FileHash'.

ordvec-manifest/src/sqlite.rs

Tests (3) +458 / -2

hash_helpers.rsAdd regression tests for 'sha256_bytes' and bounded 'sha256_reader' +53/-0

Add regression tests for 'sha256_bytes' and bounded 'sha256_reader'

• Adds tests asserting consistent digests across file/bytes/reader helpers and validating bounded-reader edge cases (exact bound, over bound, empty input). Ensures new shared hashing core behaves identically across entry points.

ordvec-manifest/tests/hash_helpers.rs

manifest.rsAssert typed classification and SHA-256 mismatch detail in load failure path +17/-2

Assert typed classification and SHA-256 mismatch detail in load failure path

• Extends an existing corrupted-artifact test to validate 'ReportIssue::classification()' returns the expected 'VerificationCode' variant. Verifies expected/actual SHA-256 fields are populated for mismatch issues.

ordvec-manifest/tests/manifest.rs

verification_codes.rsLock code-string values, reject new emit-site literals, and test JSON stability +388/-0

Lock code-string values, reject new emit-site literals, and test JSON stability

• Adds tests that pin security-relevant 'codes::*' values, scan 'src/lib.rs' to prevent reintroducing bare string literals at emit sites, and validate classification mapping coverage. Also verifies verification-report JSON remains byte-stable when structured fields are absent, and that structured fields serialize/round-trip correctly while legacy JSON still parses.

ordvec-manifest/tests/verification_codes.rs

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

1. Artifact missing misclassified 🐞 Bug ≡ Correctness

Description

ReportIssue::classification maps codes::ARTIFACT_PATH_UNAVAILABLE to
VerificationCode::ArtifactMissing, but resolve_existing_path emits path_unavailable for any
fs::canonicalize error (permission denied, I/O error, etc.), not only NotFound. Downstream consumers
that branch on VerificationCode::ArtifactMissing will incorrectly treat permission or I/O failures
as absent artifacts.

Code

ordvec-manifest/src/lib.rs[3926]

+            codes::ARTIFACT_PATH_UNAVAILABLE => VerificationCode::ArtifactMissing,

Relevance

⭐⭐⭐ High

Team previously accepted fixing misclassified verifier issue codes (row-count limit vs mismatch) in
PR #157.

PR-#157

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The classification arm maps ARTIFACT_PATH_UNAVAILABLE to ArtifactMissing. However,
resolve_existing_path emits path_unavailable for any canonicalize error, not just NotFound. The code
at lib.rs:2547-2555 shows: `Err(err) => { errors.push(ReportIssue::new(issue_codes.path_unavailable,
format!("failed to canonicalize {}: {err}", resolved_path.display()))); return None; }` — this
catches all IO errors. The same pattern applies to all PathIssueCodes instances
(ARTIFACT_PATH_ISSUES, ROW_IDENTITY_PATH_ISSUES, etc.).

ordvec-manifest/src/lib.rs[2547-2555]
ordvec-manifest/src/lib.rs[3922-3950]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description

`ReportIssue::classification()` maps `codes::ARTIFACT_PATH_UNAVAILABLE` to `VerificationCode::ArtifactMissing`. However, `resolve_existing_path` emits `path_unavailable` for **any** `fs::canonicalize` error (permission denied, I/O error, etc.), not only `NotFound`. Downstream consumers that branch on `VerificationCode::ArtifactMissing` will incorrectly treat permission or I/O failures as absent artifacts.

## Issue Context

`resolve_existing_path` in `lib.rs` emits `issue_codes.path_unavailable` for any `Err(err)` from `fs::canonicalize`, regardless of `err.kind()`. The classification arm at line 3926 then maps this code to `ArtifactMissing`, conflating two distinct failure modes.

## Fix Focus Areas

- `ordvec-manifest/src/lib.rs[3843-3864]` — add a new `ArtifactUnavailable` (or similar) variant to `VerificationCode`
- `ordvec-manifest/src/lib.rs[3922-3950]` — map `codes::ARTIFACT_PATH_UNAVAILABLE` to the new variant instead of `ArtifactMissing`
- `ordvec-manifest/tests/verification_codes.rs[199-287]` — update the classification round-trip test to cover the new variant

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[Fieldnote-Echo]

Merged feat/deterministic-manifest forward (0.7.0 lockstep bump + crossbeam-epoch RUSTSEC fix + windows/macos test-suite platform fixes — see #287 for details) and added the missing changelog entries for this branch's own surface (typed verification classification + shared hash helpers) under the 0.7.0 section. Local gate: fmt/clippy clean, 256 core + 111 manifest (all-features) tests pass, release-publish invariants hold.

[Fieldnote-Echo]

Follow-up audit round (adversarial re-review, 3 independent reviewers). The qodo finding (ARTIFACT_PATH_UNAVAILABLE→ArtifactMissing) is confirmed and fixed at root cause in 35ed4c6, and the re-review found a second gap in the same mechanism:

• resolve_existing_path emitted *_path_unavailable for every fs::canonicalize error kind (verified empirically: NotFound and EACCES/ELOOP), so a present-but-unreadable artifact classified as ArtifactMissing. Now a dedicated artifact_missing / row_identity_missing code is emitted only on ErrorKind::NotFound; ARTIFACT_PATH_UNAVAILABLE / ROW_IDENTITY_PATH_UNAVAILABLE classify Unknown (regression-pinned).
• Second gap: a missing rows.jsonl previously classified Unknown while its sha/row-count mismatches were typed — now RowIdentityMissing (new #[non_exhaustive] variant).
• classification() doc corrected (it over-claimed all security-relevant families are typed; path-policy rejections + diagnostic I/O deliberately map to Unknown).

qodo thread resolved with the evidence. ordvec-manifest --all-features 114 passed (fmt/clippy/core clean). This branch also carries #287's migration+loader fixes via merge. Note: the new commit dismisses the prior approval (stale-review policy) — needs a re-approve.