feat(parity): MOS summaries dump harness — Python↔Rust byte-exact (roadmap stage 1)

docs/notes/interprocedural-roadmap.md

@@ -163,7 +163,13 @@ the full must/may/escape evidence regardless of mode»), не хватает п
 **Критерий готовности:** на любом прогоне можно ответить «почему этот вызов
 не consume/borrow/fresh» без чтения кода моста. С началом Rust-порта у этапа
 появляется вторая роль (§2): нормализованный дамп сводок — паритетный артефакт,
-по которому диффуются Python- и Rust-стороны инференции.
+по которому диффуются Python- и Rust-стороны инференции. ✅ *(shipped)*:
+харнесс `tests/test_summaries_fixtures.py` (Python пишет голдены — точные
+байты stdout CLI) + `rust/crates/own-bridge/tests/summaries.rs`
+(`own_bridge::dump_summaries` воспроизводит каждый голден байт-в-байт:
+замороженный Layer-2 корпус фактов + синтетические MOS-кейсы — SCC-циклы,
+цепочки/циклы forward-return, extern-лог, тай-брейки слияния перегрузок,
+sig-ключи, `degraded`, non-ASCII экранирование).
 
 ## 5. Этап 2 — сигнатурный ключ: закрыть арность (1–2 недели)
 

rust/crates/own-bridge/Cargo.toml

@@ -16,5 +16,9 @@ own-ir = { path = "../own-ir" }
 own-lowered = { path = "../own-lowered" }
 serde_json.workspace = true
 
+[dev-dependencies]
+# The summaries-family manifest is parsed typed+strict in tests/summaries.rs.
+serde.workspace = true
+
 [lints]
 workspace = true

rust/crates/own-bridge/src/dump.rs

@@ -0,0 +1,208 @@
+//! The MOS parity dump — `ownlang/ownir.py::dump_summaries`, serialized as
+//! the `python -m ownlang summaries` CLI prints it (spec/Inference.md §8).
+//!
+//! The output contract is BYTE-EXACT stdout parity with the reference over
+//! the shared parity domain (scalar-metadata facts — the boundary is stated
+//! on [`dump_summaries`] and in the public API doc):
+//! `json.dumps(doc, indent=2, sort_keys=True)` plus the newline `print`
+//! appends. That serialization keeps Python's `ensure_ascii` default (unlike
+//! the Layer 2 surface, which pins `ensure_ascii=False`), so this module
+//! carries its own emitter: sorted keys at every level, 2-space indent, and
+//! `\uXXXX` escapes (surrogate pairs above the BMP) for everything outside
+//! printable ASCII — `serde_json` cannot produce that shape.
+//!
+//! Determinism is the point (INF-R1): summaries sorted by method key, the
+//! unresolved log sorted, fixed field vocabulary — the same facts yield
+//! byte-identical output regardless of `functions[]` input order, which is
+//! what makes the dump a parity artifact rather than a debug log. A failed
+//! solve degrades exactly like the reference: empty `summaries`/`unresolved`
+//! with the reason under `degraded` (INF-F6), never a crash.
+
+// `redundant_pub_crate` (nursery) conflicts with the workspace's DENY of
+// `unreachable_pub` for items in private modules; pub(crate) is the honest
+// visibility here (same stance as `mos.rs`).
+#![allow(clippy::redundant_pub_crate)]
+
+use crate::lower::{as_list, build_skeletons, py_str};
+use crate::mos;
+use crate::BridgeError;
+use own_ir::{OwnIr, OWNIR_VERSION};
+use serde_json::{json, Value};
+
+/// Render the summaries document for one `OwnIR` facts document —
+/// byte-identical to `python -m ownlang summaries` for the shared parity
+/// domain (scalar-metadata facts; the public doc on the crate-level
+/// re-export states the same boundary).
+///
+/// Scope note (the `py_str` caveat, same as the Layer 2 surface): the
+/// reference `str()`-ifies raw metadata scalars (`module`, and the
+/// per-record `name`/`file` the skeleton builder reads), and neither door
+/// validates their TYPE — a container placed where a scalar belongs would
+/// render as Python `repr` there and as JSON text here. That shape has no
+/// producer, cannot be reproduced faithfully for dicts at all
+/// (`serde_json`'s map re-sorts keys; Python `str()` keeps insertion
+/// order), and is kept OUT of the parity contract rather than
+/// half-emulated: the harness pins only scalar-metadata corpora, and any
+/// future fixture that smuggles a container in goes red on the byte diff
+/// instead of diverging silently.
+///
+/// # Errors
+/// [`BridgeError`] only if the typed facts cannot be re-serialized to JSON
+/// (not reachable for a document `OwnIr::from_json` accepted); a SOLVER
+/// failure is not an error here — it is the `degraded` branch of the
+/// document, same as the reference.
+pub(crate) fn dump_summaries(facts: &OwnIr) -> Result<String, BridgeError> {
+ let root = facts.to_value().map_err(|e| BridgeError(e.to_string()))?;
+ let root = root.as_object().cloned().unwrap_or_default();
+ // Python: `str(facts.get("module", "?"))` / `facts.get("functions", [])`
+ // (a present non-list reads as empty).
+ let module = root.get("module").map_or_else(|| "?".to_owned(), py_str);
+ let raw_fns = as_list(root.get("functions"));
+
+ let mut summaries: Vec<Value> = Vec::new();
+ let mut unresolved: Vec<String> = Vec::new();
+ let mut degraded = Value::Null;
+ match mos::solve_with_log(build_skeletons(raw_fns)) {
+ Ok((mos, log)) => {
+ unresolved = log;
+ // `sorted(summaries)` — the map key IS `MethodSummary.key` in the
+ // reference, so sorting keys sorts the dump.
+ let mut keys: Vec<&String> = mos.keys().collect();
+ keys.sort();
+ for key in keys {
+ let Some(s) = mos.get(key) else {
+ continue; // unreachable: `keys` was collected from `mos`
+ };
+ let params: Vec<Value> = s
+ .params
+ .iter()
+ .map(|p| {
+ json!({
+ "index": p.index,
+ "name": p.name,
+ "disposable": p.disposable,
+ "transfer": p.transfer.as_str(),
+ })
+ })
+ .collect();
+ // `escapes` is deliberately NOT serialized (INF-R2): no
+ // producer sets the axis, so emitting it would freeze an
+ // always-`false` lie into the parity artifact.
+ summaries.push(json!({
+ "method": key,
+ "file": s.file,
+ "line": s.line,
+ "source": s.source,
+ "params": params,
+ "returns": {"owned": s.returns},
+ }));
+ }
+ }
+ Err(e) => {
+ // Python: `except Exception as exc: f"{type(exc).__name__}: {exc}"`.
+ // The only failure a facts document can reach is the duplicate-key
+ // guard, a `ValueError` in the reference — mirror its type name.
+ degraded = Value::String(format!("ValueError: {e}"));
+ }
+ }
+
+ let doc = json!({
+ "module": module,
+ "ownir_version": OWNIR_VERSION,
+ "summaries": summaries,
+ "unresolved": unresolved,
+ "degraded": degraded,
+ });
+ let mut out = String::new();
+ emit(&doc, 0, &mut out);
+ out.push('\n'); // the newline `print` appends
+ Ok(out)
+}
+
+/// One string, escaped exactly as Python's `json.dumps` default
+/// (`ensure_ascii=True`) escapes it: printable ASCII (0x20–0x7E) literal
+/// except `"` and `\`, the five short escapes, `\uXXXX` (lowercase hex) for
+/// everything else, surrogate PAIRS for code points above the BMP.
+fn escape_py(s: &str, out: &mut String) {
+ use std::fmt::Write as _;
+ out.push('"');
+ for c in s.chars() {
+ match c {
+ '"' => out.push_str("\\\""),
+ '\\' => out.push_str("\\\\"),
+ '\n' => out.push_str("\\n"),
+ '\r' => out.push_str("\\r"),
+ '\t' => out.push_str("\\t"),
+ '\u{08}' => out.push_str("\\b"),
+ '\u{0c}' => out.push_str("\\f"),
+ ' '..='~' => out.push(c),
+ _ => {
+ let mut units = [0_u16; 2];
+ for unit in c.encode_utf16(&mut units) {
+ // Writing into a String cannot fail; the lint-honest
+ // form still avoids unwrap.
+ let _ = write!(out, "\\u{unit:04x}");
+ }
+ }
+ }
+ }
+ out.push('"');
+}
+
+/// `json.dumps(value, indent=2, sort_keys=True)`: 2-space indent, `": "` /
+/// `","` separators, keys sorted at every level, empty containers inline.
+fn emit(v: &Value, indent: usize, out: &mut String) {
+ match v {
+ Value::Null => out.push_str("null"),
+ Value::Bool(true) => out.push_str("true"),
+ Value::Bool(false) => out.push_str("false"),
+ // The document carries only i64s (lines, the version); a non-integer
+ // number cannot be constructed by `dump_summaries`.
+ Value::Number(n) => out.push_str(&n.to_string()),
+ Value::String(s) => escape_py(s, out),
+ Value::Array(items) => {
+ if items.is_empty() {
+ out.push_str("[]");
+ return;
+ }
+ out.push('[');
+ for (i, item) in items.iter().enumerate() {
+ out.push_str(if i == 0 { "\n" } else { ",\n" });
+ pad(indent.saturating_add(2), out);
+ emit(item, indent.saturating_add(2), out);
+ }
+ out.push('\n');
+ pad(indent, out);
+ out.push(']');
+ }
+ Value::Object(map) => {
+ if map.is_empty() {
+ out.push_str("{}");
+ return;
+ }
+ let mut keys: Vec<&String> = map.keys().collect();
+ keys.sort();
+ out.push('{');
+ for (i, key) in keys.iter().enumerate() {
+ out.push_str(if i == 0 { "\n" } else { ",\n" });
+ pad(indent.saturating_add(2), out);
+ escape_py(key, out);
+ out.push_str(": ");
+ emit(
+ map.get(key.as_str()).unwrap_or(&Value::Null),
+ indent.saturating_add(2),
+ out,
+ );
+ }
+ out.push('\n');
+ pad(indent, out);
+ out.push('}');
+ }
+ }
+}
+
+fn pad(n: usize, out: &mut String) {
+ for _ in 0..n {
+ out.push(' ');
+ }
+}

rust/crates/own-bridge/src/lib.rs

@@ -12,16 +12,24 @@
 //! **Pure transformation**: [`lower`] maps a typed [`own_ir::OwnIr`] document
 //! to an [`own_lowered::LoweredDocument`] (or a [`BridgeError`] whose message
 //! text is part of the parity surface — Python projects it as the `Rejected`
-//! form). No filesystem, no CLI, no diagnostics, no analysis. The tolerant
-//! door, `OwnIR` validation parity, MOS contract *changes*, and analysis
-//! wiring are all out of scope (#294 stays open; the `tolerant_unknown_kind`
-//! fixture stays Python-only).
+//! form), and [`dump_summaries`] renders the MOS summaries document
+//! byte-identically to `python -m ownlang summaries` over the shared
+//! scalar-metadata parity domain (the inference layer's parity artifact,
+//! spec/Inference.md §8; see the function's contract for the domain
+//! boundary). No filesystem, no CLI, no
+//! diagnostics, no analysis. `OwnIR` validation parity, MOS contract
+//! *changes*, and analysis wiring stay out of scope (#294 OD-2 landed:
+//! IR4-everywhere — `tolerant_unknown_kind` is a shared `rust_replay` case
+//! whose `Rejected` golden pins the fail-loud text on both sides).
 //!
 //! The oracle is byte-exact: for every `rust_replay: true` manifest case,
 //! `facts → OwnIr::from_json → lower → own_lowered::to_canonical_json` must
-//! equal the committed Python golden (`tests/replay.rs`). The goldens are
+//! equal the committed Python golden (`tests/replay.rs`), and every
+//! summaries-family case must reproduce its `*.summaries.json` golden
+//! through [`dump_summaries`] (`tests/summaries.rs`). The goldens are
 //! expected output ONLY — never an input to construction.
 
+mod dump;
 mod lower;
 mod mos;
 
@@ -50,3 +58,27 @@ impl std::error::Error for BridgeError {}
 pub fn lower(facts: &OwnIr) -> Result<LoweredDocument, BridgeError> {
  lower::lower(facts)
 }
+
+/// Render the MOS summaries document for one `OwnIR` facts document.
+///
+/// Byte-identical to `python -m ownlang summaries` (`json.dumps(doc,
+/// indent=2, sort_keys=True)` + the trailing newline) **for the shared
+/// parity domain**: facts whose metadata fields consumed through Python
+/// `str()` — `module`, `functions[].name`/`file`, call `callee`/`sig` — are
+/// JSON scalars. Every real producer emits scalars there, and the fixture
+/// corpus pins only such documents. Container-valued metadata is OUTSIDE
+/// this stage-1 contract: both doors accept it, but the reference renders
+/// it as Python `repr` while this port renders JSON text, so the outputs
+/// diverge without a runtime error. Door-wide type validation (or exact
+/// container-repr parity) is a separate #294-class door decision — see the
+/// scope note on the implementation for why neither is folded in here.
+///
+/// A solver failure is not an error: it is the document's `degraded`
+/// branch, exactly like the reference (INF-F6).
+///
+/// # Errors
+/// [`BridgeError`] only if the typed facts cannot be re-serialized to JSON
+/// (not reachable for a document [`OwnIr::from_json`] accepted).
+pub fn dump_summaries(facts: &OwnIr) -> Result<String, BridgeError> {
+ dump::dump_summaries(facts)
+}