feat(domain): R5.6 prepared, fingerprint convention and registry inert, switch patch

canonical_json (RFC 8785), sheet_fingerprint behind feature fingerprint,
TRUSTED_ALIASES (one equine pair), equivalence and check_declared; tests against
the RFC vectors, the V8 numbers, an independent Node reference and the archives.
No consumer wired: the switch is a rehearsed patch under .claude/tasks/plans.
This commit is contained in:
bchanot committed 2026-10-24 14:36:01 +02:00
1 parent 1f8873dbce
commit 3b9a395d43
12 files changed
+1004 -1

No files matched your search

+8 -1
View File
@@ -24,7 +24,10 @@ pdf-write = ["pdf-read"]
cli = ["pdf-read", "pdf-write"]
# The anatomical pipeline (R5): legacy importer, curation, generated files and their
# formatting, the `import-equine` tool. Never enabled by the wasm facade or the worker.
curation = ["dep:sha2", "dep:icu_normalizer"]
curation = ["fingerprint", "dep:icu_normalizer"]
# The sheet fingerprint `sha256-rfc8785-validated-v1` (R5.6, prepared, not active): the hashing
# half of `domain::sheet::fingerprint`; the registry and the comparison compile without it.
fingerprint = ["dep:sha2"]
# The sheet-asset upload tool (R5.5): the `upload-sheet-assets` binary, a local-stack operator
# tool. The rules are in `curation::upload`; only the binary reaches the network.
upload = ["curation", "dep:ureq"]
@@ -151,3 +154,7 @@ required-features = ["curation"]
[[test]]
name = "upload_tool"
required-features = ["upload"]
[[test]]
name = "sheet_fingerprint"
required-features = ["fingerprint", "pdf-read"]
+223
View File
@@ -0,0 +1,223 @@
//! The sheet fingerprint convention `sha256-rfc8785-validated-v1` (D-R5.6, owner 2026-10-24,
//! BDR-068) and the trusted alias registry. PREPARED, NOT ACTIVE: no reader, writer or
//! generated file uses this module until the owner's switch signal (RUST.md §11.19).
//!
//! The value is the SHA-256 of the RFC 8785 (JCS) text of the validated document: the strict
//! typed reading of the R2 contract (`AnatomicalSheetDocument`, Zod's defaults filled, unknown
//! keys dropped) with zero integrity issue, serialised back. JCS: members sorted recursively by
//! the UTF-16 code units of their names, numbers as ECMAScript `Number::toString`, strings with
//! the `JSON.stringify` escape set and every other character kept as is (no Unicode
//! normalisation), no whitespace, UTF-8. `v1` freezes these rules and the validation.
use serde_json::Value;
use crate::json::js_number;
/// The convention's name, as `sheet-ref.json` will declare it at the switch.
pub const FINGERPRINT_CONVENTION: &str = "sha256-rfc8785-validated-v1";
/// The pre-switch convention: SHA-256 of the Prettier-formatted `document.json` bytes.
pub const LEGACY_CONVENTION: &str = "sha256-prettier-file-bytes-v0";
/// One trusted equivalence: under `sheet_id`, the content whose canonical fingerprint is
/// `canonical` was stamped `alias` under `alias_convention`. Bound to the sheet and to that
/// content, never global; built from the frozen oracles, never from an archive, a bundle or the
/// database.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TrustedAlias {
pub sheet_id: &'static str,
pub canonical: &'static str,
pub alias: &'static str,
pub alias_convention: &'static str,
}
/// The registry, the only authority over equivalences. Equine draft: `alias` is the committed
/// `sheet-ref.json` value and `oracles/r5/fingerprints.json` `today_file_bytes`; `canonical` is
/// the same oracle's `b_rfc8785_validated`, recomputed by `sheet_fingerprint` (test).
pub const TRUSTED_ALIASES: &[TrustedAlias] = &[TrustedAlias {
sheet_id: "503dc301-a8b1-50d4-9e44-0919b2fc2916",
canonical: "12d788727c1e532641bd5b3a7ecf39dbdd25e70350f8a76be5ca917b262874e2",
alias: "27c7383c445c73dc2001ebf4794a3ea63d416910bbbaa0d7848dd720de7c2660",
alias_convention: LEGACY_CONVENTION,
}];
/// How two fingerprints of one sheet relate. The raw values stay with the caller, so a
/// diagnostic can still print both.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Equivalence {
Identical,
/// Different values the registry binds to the same content of this sheet.
TrustedAlias,
Different,
}
impl Equivalence {
pub fn same_document(self) -> bool {
self != Self::Different
}
}
/// `a` and `b`, two fingerprints stamped for `sheet_id`: equal, a registered pair of that sheet
/// (either way round), or different. A real content change is never registered, so it stays
/// `Different` and rebases as before.
pub fn equivalence(sheet_id: &str, a: &str, b: &str) -> Equivalence {
if a == b {
return Equivalence::Identical;
}
let paired = TRUSTED_ALIASES.iter().any(|entry| {
entry.sheet_id == sheet_id
&& ((entry.canonical == a && entry.alias == b)
|| (entry.canonical == b && entry.alias == a))
});
if paired {
Equivalence::TrustedAlias
} else {
Equivalence::Different
}
}
/// Why declared metadata contradicts the registry.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AliasRefusal {
/// The declared convention is not `v1`.
UnknownConvention(String),
/// A declared alias the registry does not bind to this sheet and canonical value.
Untrusted(String),
}
/// Checks what a `sheet-ref.json` declares (descriptive only): the convention must be `v1` and
/// every listed alias must be registered for this sheet and this canonical value. A
/// declaration never creates an equivalence.
pub fn check_declared(
sheet_id: &str,
canonical: &str,
convention: &str,
aliases: &[String],
) -> Result<(), AliasRefusal> {
if convention != FINGERPRINT_CONVENTION {
return Err(AliasRefusal::UnknownConvention(convention.to_owned()));
}
for alias in aliases {
let trusted = TRUSTED_ALIASES.iter().any(|entry| {
entry.sheet_id == sheet_id && entry.canonical == canonical && entry.alias == alias
});
if !trusted {
return Err(AliasRefusal::Untrusted(alias.clone()));
}
}
Ok(())
}
/// RFC 8785 text of a JSON value. `None` for a number with no I-JSON form (never produced by
/// the core's parser, which refuses non-finite values).
pub fn canonical_json(value: &Value) -> Option<String> {
let mut out = String::new();
write_value(value, &mut out)?;
Some(out)
}
fn write_value(value: &Value, out: &mut String) -> Option<()> {
match value {
Value::Null => out.push_str("null"),
Value::Bool(flag) => out.push_str(if *flag { "true" } else { "false" }),
Value::Number(number) => {
let float = number.as_f64().filter(|f| f.is_finite())?;
out.push_str(&js_number(float));
}
Value::String(text) => write_string(text, out),
Value::Array(items) => {
out.push('[');
for (index, item) in items.iter().enumerate() {
if index > 0 {
out.push(',');
}
write_value(item, out)?;
}
out.push(']');
}
Value::Object(map) => write_object(map, out)?,
}
Some(())
}
fn write_object(map: &serde_json::Map<String, Value>, out: &mut String) -> Option<()> {
let mut entries: Vec<(Vec<u16>, &String, &Value)> = map
.iter()
.map(|(key, item)| (key.encode_utf16().collect(), key, item))
.collect();
entries.sort_by(|left, right| left.0.cmp(&right.0));
out.push('{');
for (index, (_, key, item)) in entries.iter().enumerate() {
if index > 0 {
out.push(',');
}
write_string(key, out);
out.push(':');
write_value(item, out)?;
}
out.push('}');
Some(())
}
/// `JSON.stringify` of a string: `"` `\` and the controls escaped (short forms where JSON has
/// them, `\u00xx` lowercase otherwise), everything else verbatim.
fn write_string(text: &str, out: &mut String) {
out.push('"');
for character in text.chars() {
match character {
'"' => out.push_str("\\\""),
'\\' => out.push_str("\\\\"),
'\u{8}' => out.push_str("\\b"),
'\u{c}' => out.push_str("\\f"),
'\n' => out.push_str("\\n"),
'\r' => out.push_str("\\r"),
'\t' => out.push_str("\\t"),
control if u32::from(control) < 0x20 => {
out.push_str(&format!("\\u{:04x}", u32::from(control)));
}
other => out.push(other),
}
}
out.push('"');
}
#[cfg(feature = "fingerprint")]
pub use hashing::{FingerprintError, sheet_fingerprint};
#[cfg(feature = "fingerprint")]
mod hashing {
use sha2::{Digest, Sha256};
use super::canonical_json;
use crate::domain::js::parse_json;
use crate::domain::sheet::schema::AnatomicalSheetDocument;
use crate::domain::sheet::validate::validate_sheet_document;
/// Why a document has no fingerprint: an invalid sheet is never stamped.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FingerprintError {
Parse(String),
Shape(String),
/// The integrity rules found issues (their count).
Invalid(usize),
Canonical,
}
/// `sha256-rfc8785-validated-v1` of a document text: strict parse, R2 shape, zero
/// integrity issue, then JCS of the typed reading serialised back.
pub fn sheet_fingerprint(text: &str) -> Result<String, FingerprintError> {
let value = parse_json(text).map_err(|e| FingerprintError::Parse(e.to_string()))?;
let document: AnatomicalSheetDocument =
serde_json::from_value(value).map_err(|e| FingerprintError::Shape(e.to_string()))?;
let issues = validate_sheet_document(&document);
if !issues.is_empty() {
return Err(FingerprintError::Invalid(issues.len()));
}
let validated =
serde_json::to_value(&document).map_err(|e| FingerprintError::Shape(e.to_string()))?;
let canonical = canonical_json(&validated).ok_or(FingerprintError::Canonical)?;
Ok(Sha256::digest(canonical.as_bytes())
.iter()
.map(|byte| format!("{byte:02x}"))
.collect())
}
}
+1
View File
@@ -3,6 +3,7 @@
pub mod check;
pub mod create;
pub mod fingerprint;
pub mod index;
pub mod index_data;
pub mod loaded;
@@ -0,0 +1,40 @@
{
"frozen_from": "Node v24.21.0",
"cases": [
{
"input": "[1e21, 1e-7, 1E+2, 0.1, -0, 5e-324, 1.7976931348623157e308, 123456789012345678901, 9007199254740993, 100, 1.5e-6, 0.000001, 1e20, 999999999999999999999]",
"canonical": "[1e+21,1e-7,100,0.1,0,5e-324,1.7976931348623157e+308,123456789012345680000,9007199254740992,100,0.0000015,0.000001,100000000000000000000,1e+21]",
"sha256": "454757d41a64c2a76e8fd9c555ce7f7732241ac8d192a731ccb880d5cdde1f25"
},
{
"input": "{\"\\ud83d\\ude00\": 1, \"\\ufb33\": 2, \"\\u00e9\": 3, \"e\\u0301\": 4, \"Z\": 5, \"a\": 6, \"\": 7, \"aa\": 8, \"\\u0080\": 9}",
"canonical": "{\"\":7,\"Z\":5,\"a\":6,\"aa\":8,\"é\":4,\"€\":9,\"é\":3,\"😀\":1,\"דּ\":2}",
"sha256": "781d348d29b6dc2fcb75ed58f847fbc19ebb6f2dd526e5aa67e130a074a7200a"
},
{
"input": "{\"s\": \"\\u0000\\u0001\\u001f\\b\\f\\n\\r\\t\\\"\\\\/\\u007f\\u2028\\u2029\\u00e9e\\u0301\\ud83d\\ude00\"}",
"canonical": "{\"s\":\"\\u0000\\u0001\\u001f\\b\\f\\n\\r\\t\\\"\\\\/

éé😀\"}",
"sha256": "ecaac6f9c64eb5f89acb33f7f98b840e3c07b8c91551e184af89aa1da702d0bb"
},
{
"input": "{\"b\": {\"z\": [true, false, null, {\"y\": 1, \"x\": [ ]}], \"a\": {}}, \"a\": [[[]]]}",
"canonical": "{\"a\":[[[]]],\"b\":{\"a\":{},\"z\":[true,false,null,{\"x\":[],\"y\":1}]}}",
"sha256": "326c7cd13dafbbe0412b029969bf0b2994bdeea90313ca59b2cc4c5015c15447"
},
{
"input": "{\"geometry\": {\"cx\": 743.0451049804688, \"cy\": 469.1115417480469, \"r\": 12}, \"name\": {\"fr\": \"Atlas (C1)\", \"en\": \"Atlas\"}}",
"canonical": "{\"geometry\":{\"cx\":743.0451049804688,\"cy\":469.1115417480469,\"r\":12},\"name\":{\"en\":\"Atlas\",\"fr\":\"Atlas (C1)\"}}",
"sha256": "0fa3704e87fb9f065b20bdd8d70c66705a20a33366f6ae8546adeb83ac1053f0"
},
{
"input": "{\"k\": 1, \"k\": 2}",
"canonical": "{\"k\":2}",
"sha256": "1ddca3d1f7a33ce87c75de54e2b6a7ee0e52cf11cb8b8041e102b8477d5b1a23"
},
{
"input": "[-1.0, 2.50, 1e0, -1e-0, 0.1e1, 12345678.9, 4.35, 0.3, 1e-6, 1e-5]",
"canonical": "[-1,2.5,1,-1,1,12345678.9,4.35,0.3,0.000001,0.00001]",
"sha256": "a2d500ce5093d2214d6e7b78163853211d5c8a43317ca81f0eac4f7aebd650e5"
}
]
}
+256
View File
@@ -0,0 +1,256 @@
//! R5.6 preparation (owner 2026-10-24 « arbitrage D-R5.6 »): the convention
//! `sha256-rfc8785-validated-v1` and the trusted alias registry, PREPARED, NOT ACTIVE. The RFC
//! 8785 vectors, the V8 number oracle, the independent Node differential, the draft's frozen
//! value, the registry's contract and a census of the historical archives (JSON fixtures and
//! every fixture PDF's attachment) under the comparison the five consumers will use.
#![allow(clippy::disallowed_methods, clippy::unwrap_used, clippy::expect_used)]
mod common;
use faunosteo_core::domain::js::parse_json;
use faunosteo_core::domain::sheet::fingerprint::{
AliasRefusal, Equivalence, FINGERPRINT_CONVENTION, FingerprintError, TRUSTED_ALIASES,
canonical_json, check_declared, equivalence, sheet_fingerprint,
};
use faunosteo_core::pdf::read::probe::{ProbeLimits, read_attached_document};
use serde_json::Value;
use sha2::{Digest, Sha256};
const SHEET: &str = "503dc301-a8b1-50d4-9e44-0919b2fc2916";
const ALIAS: &str = "27c7383c445c73dc2001ebf4794a3ea63d416910bbbaa0d7848dd720de7c2660";
const CANONICAL: &str = "12d788727c1e532641bd5b3a7ecf39dbdd25e70350f8a76be5ca917b262874e2";
fn oracle(name: &str) -> Value {
serde_json::from_str(&common::repo_file(&format!(
"crates/core/tests/oracles/r5/{name}"
)))
.unwrap()
}
fn sha256(text: &str) -> String {
Sha256::digest(text.as_bytes())
.iter()
.map(|b| format!("{b:02x}"))
.collect()
}
#[test]
fn the_rfc_8785_vectors_are_reproduced() {
let vectors = oracle("fingerprints.json")["rfc8785_vectors"].clone();
for vector in vectors.as_array().unwrap() {
let input = parse_json(vector["input"].as_str().unwrap()).unwrap();
assert_eq!(
canonical_json(&input).unwrap(),
vector["canonical"].as_str().unwrap()
);
}
}
#[test]
fn numbers_print_as_v8_on_the_whole_oracle() {
let rows = oracle("numbers.json")["rows"].clone();
let rows = rows.as_array().unwrap();
assert_eq!(rows.len(), 44_322);
for row in rows {
let bits = u64::from_str_radix(row[0].as_str().unwrap(), 16).unwrap();
let value = Value::from(f64::from_bits(bits));
assert_eq!(
canonical_json(&value).unwrap(),
row[1].as_str().unwrap(),
"{bits:016x}"
);
}
}
#[test]
fn the_independent_node_reference_agrees_case_by_case() {
let frozen = oracle("fingerprint-differential.json");
for case in frozen["cases"].as_array().unwrap() {
let input = parse_json(case["input"].as_str().unwrap()).unwrap();
let canonical = canonical_json(&input).unwrap();
assert_eq!(canonical, case["canonical"].as_str().unwrap());
assert_eq!(sha256(&canonical), case["sha256"].as_str().unwrap());
}
}
#[test]
fn unicode_is_kept_and_ordered_by_utf16_units() {
// U+FB33 sorts after U+1F600 by code point, before it by UTF-16 units (0xFB33 > 0xD83D).
let value = parse_json(r#"{"דּ":1,"😀":2,"é":3,"é":4}"#).unwrap();
assert_eq!(
canonical_json(&value).unwrap(),
"{\"e\u{301}\":4,\"\u{e9}\":3,\"\u{1F600}\":2,\"\u{FB33}\":1}"
);
}
#[test]
fn the_draft_gives_the_frozen_validated_value() {
let text = common::repo_file("supabase/seed/anatomical-sheets/equine/draft/document.json");
assert_eq!(sha256(&text), ALIAS);
assert_eq!(sheet_fingerprint(&text).unwrap(), CANONICAL);
let artifacts = oracle("fingerprints.json")["artifacts"].clone();
let draft = artifacts
.as_array()
.unwrap()
.iter()
.find(|a| a["file"].as_str().unwrap().ends_with("draft/document.json"))
.unwrap()
.clone();
assert_eq!(draft["b_rfc8785_validated"], CANONICAL);
assert_eq!(draft["today_file_bytes"], ALIAS);
}
#[test]
fn an_invalid_or_malformed_document_has_no_fingerprint() {
let text = common::repo_file("supabase/seed/anatomical-sheets/equine/draft/document.json");
let mut value: Value = serde_json::from_str(&text).unwrap();
let first = value["annotations"][0]["id"].clone();
value["annotations"][1]["id"] = first;
let duplicated = serde_json::to_string(&value).unwrap();
assert!(matches!(sheet_fingerprint(&duplicated), Err(FingerprintError::Invalid(n)) if n > 0));
assert!(matches!(
sheet_fingerprint("[1]"),
Err(FingerprintError::Shape(_))
));
assert!(matches!(
sheet_fingerprint("{"),
Err(FingerprintError::Parse(_))
));
}
#[test]
fn the_registry_holds_one_pair_bound_to_the_equine_sheet() {
assert_eq!(TRUSTED_ALIASES.len(), 1);
assert_eq!(FINGERPRINT_CONVENTION, "sha256-rfc8785-validated-v1");
assert_eq!(
equivalence(SHEET, CANONICAL, CANONICAL),
Equivalence::Identical
);
assert_eq!(
equivalence(SHEET, CANONICAL, ALIAS),
Equivalence::TrustedAlias
);
assert_eq!(
equivalence(SHEET, ALIAS, CANONICAL),
Equivalence::TrustedAlias
);
let other_sheet = "00000000-0000-0000-0000-000000000000";
assert_eq!(
equivalence(other_sheet, CANONICAL, ALIAS),
Equivalence::Different
);
let other_content = "a".repeat(64);
assert_eq!(
equivalence(SHEET, &other_content, ALIAS),
Equivalence::Different
);
assert_eq!(
equivalence(SHEET, &other_content, CANONICAL),
Equivalence::Different
);
}
#[test]
fn declared_metadata_never_creates_an_equivalence() {
let aliases = vec![ALIAS.to_owned()];
assert_eq!(
check_declared(SHEET, CANONICAL, FINGERPRINT_CONVENTION, &aliases),
Ok(())
);
assert_eq!(
check_declared(SHEET, CANONICAL, FINGERPRINT_CONVENTION, &[]),
Ok(())
);
let forged = vec!["b".repeat(64)];
assert_eq!(
check_declared(SHEET, CANONICAL, FINGERPRINT_CONVENTION, &forged),
Err(AliasRefusal::Untrusted("b".repeat(64)))
);
let foreign = "00000000-0000-0000-0000-000000000000";
assert!(check_declared(foreign, CANONICAL, FINGERPRINT_CONVENTION, &aliases).is_err());
assert!(check_declared(SHEET, &"c".repeat(64), FINGERPRINT_CONVENTION, &aliases).is_err());
assert!(
check_declared(
SHEET,
ALIAS,
FINGERPRINT_CONVENTION,
&[CANONICAL.to_owned()]
)
.is_err()
);
assert_eq!(
check_declared(SHEET, CANONICAL, "sha256-prettier-file-bytes-v0", &aliases),
Err(AliasRefusal::UnknownConvention(
"sha256-prettier-file-bytes-v0".into()
))
);
}
/// Every `sheet` reference of a report found in `value` (bare report or envelope).
fn stamps(value: &Value, found: &mut Vec<(String, String)>) {
match value {
Value::Object(map) => {
if let (Some(id), Some(sha)) = (
map.get("sheetId").and_then(Value::as_str),
map.get("documentSha256").and_then(Value::as_str),
) {
found.push((id.to_owned(), sha.to_owned()));
}
map.values().for_each(|item| stamps(item, found));
}
Value::Array(items) => items.iter().for_each(|item| stamps(item, found)),
_ => {}
}
}
fn files(dir: &std::path::Path, out: &mut Vec<std::path::PathBuf>) {
for entry in std::fs::read_dir(dir).unwrap() {
let path = entry.unwrap().path();
if path.is_dir() {
files(&path, out);
} else {
out.push(path);
}
}
}
#[test]
fn historical_archives_open_as_the_same_document_only_through_the_registered_pair() {
let mut paths = Vec::new();
files(
std::path::Path::new(&common::repo_path("apps/app/tests/fixtures")),
&mut paths,
);
let mut found = Vec::new();
let mut pdfs = 0;
for path in &paths {
let bytes = std::fs::read(path).unwrap();
let text = match path.extension().and_then(|e| e.to_str()) {
Some("json") => String::from_utf8(bytes).ok(),
Some("pdf") => read_attached_document(&bytes, ProbeLimits::UNBOUNDED)
.ok()
.map(|located| {
pdfs += 1;
located.text.into_owned()
}),
_ => None,
};
if let Some(value) = text.and_then(|t: String| serde_json::from_str::<Value>(&t).ok()) {
stamps(&value, &mut found);
}
}
assert!(pdfs > 50, "{pdfs} attachments read");
let mut same = 0;
for (sheet, sha) in &found {
let verdict = equivalence(sheet, sha, CANONICAL);
let expected = sheet == SHEET && sha == ALIAS;
assert_eq!(verdict.same_document(), expected, "{sheet} {sha}");
same += usize::from(expected);
}
// Every authentic stamp of the equine draft is the alias; the synthetic ones stay different.
println!(
"census: {pdfs} PDF attachments, {} stamps, {same} alias",
found.len()
);
assert!(same > 30, "{same} of {}", found.len());
}