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:
1 parent
1f8873dbce
commit
3b9a395d43
12 files changed
+1004
-1
No files matched your search
@@ -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())
|
||||
}
|
||||
}
|
||||
@@ -3,6 +3,7 @@
|
||||
|
||||
pub mod check;
|
||||
pub mod create;
|
||||
pub mod fingerprint;
|
||||
pub mod index;
|
||||
pub mod index_data;
|
||||
pub mod loaded;
|
||||
|
||||
Reference in new issue
Block a user