Add the Python API over grund-core and prove binding parity

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["crates/grund-core", "crates/grund-cli", "crates/grund-lsp", "tests/integration"]
+members = ["crates/grund-core", "crates/grund-cli", "crates/grund-lsp", "crates/grund-py", "tests/integration"]
 default-members = ["crates/grund-cli"]
 resolver = "3"
 

README.md

@@ -199,7 +199,7 @@ See the [review guide](docs/user-facing/reviewing.md) for citation blast radius
 cargo install grund
 ```
 
-That installs the `grund` binary from the [`grund` crate on crates.io](https://crates.io/crates/grund) onto your `PATH`. npm and PyPI bindings are planned — see [`FS-distribution`](docs/functional-spec/FS-distribution.md).
+That installs the `grund` binary from the [`grund` crate on crates.io](https://crates.io/crates/grund) onto your `PATH`. The [Python API](docs/user-facing/python-api.md) installs locally with `python -m pip install .`; [its example](examples/python-api/) shows `import grund`. npm support and PyPI publication remain planned ([§FS-distribution.3.3.7](docs/functional-spec/FS-distribution.md#337-local-source-and-typing-handoff)).
 
 This README is itself under spec: [§REQ-readme](docs/requirements/REQ-readme.md#req-readme-the-readme-is-the-grounded-shop-window) — every example above is captured from this repository, and the citations here are checked by `grund check` like any other scanned file's.
 

crates/grund-core/Cargo.toml

@@ -9,7 +9,7 @@ license.workspace = true
 repository.workspace = true
 homepage.workspace = true
 readme = "README.md"
-include = ["src/**", "assets/**", "Cargo.toml", "README.md"]
+include = ["src/**", "assets/**", "examples/**", "Cargo.toml", "README.md"]
 
 [dependencies]
 ignore = "0.4"
@@ -22,6 +22,11 @@ anyhow = "1"
 once_cell = "1"
 rayon = "1"
 unicode-normalization = "0.1"
+serde_json = "1"
+
+[[example]]
+name = "grund-binding-oracle"
+path = "examples/grund-binding-oracle.rs"
 
 [features]
 # Black-box CLI tests use this opt-in observer to prove a batch loads one

crates/grund-core/examples/binding_oracle/canonical.rs

@@ -0,0 +1,82 @@
+//! Independent canonical-byte encoder (§FS-distribution.3.0.3).
+
+use serde_json::Value;
+
+pub(super) fn encode(value: &Value) -> Vec<u8> {
+    let mut output = String::new();
+    append(value, &mut output);
+    output.push('\n');
+    output.into_bytes()
+}
+
+fn string(value: &str, out: &mut String) {
+    out.push('"');
+    for c in value.chars() {
+        match c {
+            '"' => out.push_str("\\\""),
+            '\\' => out.push_str("\\\\"),
+            '\n' => out.push_str("\\n"),
+            '\r' => out.push_str("\\r"),
+            '\t' => out.push_str("\\t"),
+            c if c < '\u{20}' => out.push_str(&format!("\\u{:04x}", c as u32)),
+            c => out.push(c),
+        }
+    }
+    out.push('"');
+}
+
+fn append(value: &Value, out: &mut String) {
+    match value {
+        Value::Null => out.push_str("null"),
+        Value::Bool(b) => out.push_str(if *b { "true" } else { "false" }),
+        Value::Number(n) => out.push_str(&n.to_string()),
+        Value::String(s) => string(s, out),
+        Value::Array(values) => {
+            out.push('[');
+            for (index, value) in values.iter().enumerate() {
+                if index > 0 {
+                    out.push(',');
+                }
+                append(value, out);
+            }
+            out.push(']');
+        }
+        Value::Object(values) => {
+            let mut keys = values.keys().collect::<Vec<_>>();
+            keys.sort_by(|a, b| a.as_bytes().cmp(b.as_bytes()));
+            out.push('{');
+            for (index, key) in keys.into_iter().enumerate() {
+                if index > 0 {
+                    out.push(',');
+                }
+                string(key, out);
+                out.push(':');
+                append(&values[key], out);
+            }
+            out.push('}');
+        }
+    }
+}
+
+pub(super) fn base64(bytes: &[u8]) -> String {
+    const ALPHABET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    let mut result = String::new();
+    for chunk in bytes.chunks(3) {
+        let a = chunk[0] as usize;
+        let b = chunk.get(1).copied().unwrap_or(0) as usize;
+        let c = chunk.get(2).copied().unwrap_or(0) as usize;
+        result.push(ALPHABET[a >> 2] as char);
+        result.push(ALPHABET[((a & 3) << 4) | (b >> 4)] as char);
+        result.push(if chunk.len() > 1 {
+            ALPHABET[((b & 15) << 2) | (c >> 6)] as char
+        } else {
+            '='
+        });
+        result.push(if chunk.len() > 2 {
+            ALPHABET[c & 63] as char
+        } else {
+            '='
+        });
+    }
+    result
+}