feat(rust): #259 slice 2 — own-lowered, typed Layer 2 replay/emitter

The typed Rust half of the frozen Layer 2 contract (LOWERED_VERSION 1): a
strict data model of the normalized lowered representation plus the
canonical emitter, replaying the Python-authored goldens byte-for-byte.
No lowering, no OwnIR validation, no MOS, no analysis wiring — this slice
proves Rust can carry and emit the exact surface before anything derives it.

* crates/own-lowered — a LEAF data crate (own-diagnostics precedent; the
  DAG lock in own-diagnostics/tests/dag.rs is widened deliberately with the
  leaf entry and the rationale: the future own-bridge will CONSTRUCT these
  types, never the reverse). Model mirrors ownlang/lowered.py's frozen
  normalization decisions field-for-field: declaration order = canonical
  JSON order; always-written nullable fields are Option WITHOUT skip; the
  handle-entry allowlist keys are Option WITH skip, `handle` first; the
  closed Stmt vocabulary under the `stmt` tag; Rejected carries the
  fail-loud error text. Every shape is deny_unknown_fields — a Python-side
  surface change cannot slip past the typed replay.
* tests/replay.rs — reads manifest.json (typed, strict), requires
  lowered_version == LOWERED_VERSION, both fixture halves on disk for every
  case, then for each rust_replay: true case parses the golden and asserts
  the canonical re-emit is byte-identical (>= 25 shared cases). The
  rust_replay: false set is asserted to be exactly the OD-2/#294 snapshot —
  Python-only by ledger decision, not silently skipped.

serde_json's pretty printer reproduces Python json.dumps(indent=2,
ensure_ascii=False) exactly on this surface — proven by the byte-equality
suite, not assumed. cargo fmt/clippy clean, full workspace tests green
(incl. the DAG fitness test), Python suite untouched and green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Claude-Session: https://claude.ai/code/session_01MdYFKUaygHz1T9H1qJ7BqK

Author: claude

rust/Cargo.lock

@@ -8,7 +8,7 @@
 
 [workspace]
 resolver = "2"
-members = ["crates/own-ir", "crates/own-syntax", "crates/own-cfg", "crates/own-diagnostics", "crates/own-analysis"]
+members = ["crates/own-ir", "crates/own-syntax", "crates/own-cfg", "crates/own-diagnostics", "crates/own-analysis", "crates/own-lowered"]
 
 [workspace.package]
 edition = "2021"

rust/Cargo.toml

@@ -33,6 +33,13 @@ fn allowed_edges() -> HashMap<&'static str, BTreeSet<&'static str>> {
     m.insert("own-cfg", ["own-ir", "own-syntax"].into_iter().collect());
     // The invariant #214 is about: only the span leaf, never the solver/parser.
     m.insert("own-diagnostics", std::iter::once("own-ir").collect());
+    // The Layer 2 parity surface (#259): a DATA leaf like own-diagnostics —
+    // the typed model + canonical emitter of the normalized lowered
+    // representation. It deliberately depends on NO workspace crate: the
+    // future own-bridge will CONSTRUCT these types (own-bridge → own-lowered),
+    // never the reverse, and the surface must stay implementable without the
+    // lowering that fills it.
+    m.insert("own-lowered", BTreeSet::new());
     // own-analysis CONSTRUCTS diagnostics and consumes the cfg lowering. It reads
     // the effect type through `own_cfg::Effect`, NOT the parser — so there is no
     // production own-syntax edge (own-syntax is a dev-only edge for its tests).

rust/crates/own-diagnostics/tests/dag.rs

@@ -0,0 +1,22 @@
+[package]
+name = "own-lowered"
+description = "Layer 2 normalized-lowered-representation surface: typed model + canonical emitter replaying the Python-authored goldens (tests/fixtures/lowered, LOWERED_VERSION 1) — the data half of the own-bridge parity contract (P-022 #259); no lowering, no MOS, no analysis wiring"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+publish.workspace = true
+version = "0.1.0"
+
+# A LEAF data crate, like own-diagnostics: it models the Layer 2 JSON surface
+# (spec/Bridge.md §6, ownlang/lowered.py is the authoritative Python twin) and
+# re-emits it byte-for-byte. It deliberately depends on NO other own-* crate —
+# the future own-bridge will construct these types from real lowering; this
+# crate must stay implementable without it (typed replay first, derivation
+# later). serde_json is a REGULAR dependency: the canonical emitter is the
+# crate's purpose, not a test aid.
+[dependencies]
+serde = { workspace = true }
+serde_json = { workspace = true }
+
+[lints]
+workspace = true

rust/crates/own-lowered/Cargo.toml

@@ -0,0 +1,27 @@
+//! The Layer 2 parity surface, typed (P-022 #259, spec/Bridge.md §6).
+//!
+//! `ownlang/lowered.py` is the authoritative Python emitter of the normalized
+//! lowered representation; `tests/fixtures/lowered/` holds its frozen
+//! facts/golden pairs under `manifest.json`. This crate is the **typed Rust
+//! half of that contract**: a strict (`deny_unknown_fields`) data model of the
+//! surface plus the canonical emitter that re-serializes it **byte-for-byte**
+//! (2-space indent, fixed field order, raw UTF-8, trailing newline).
+//!
+//! Deliberately NOT here (next slices, gated separately): deriving these
+//! documents from `OwnIR` facts (the lowering itself), `OwnIR` validation,
+//! MOS inference, and any analysis wiring. A `rust_replay: false` manifest
+//! case is a Python-only behavior snapshot pinning an open decision (#294)
+//! and is not replayed by this crate's parity suite.
+//!
+//! Every shape here mirrors the frozen normalization decisions in the Python
+//! emitter's docstring; a field added there without a matching change here (or
+//! vice-versa) fails the replay suite, and `LOWERED_VERSION` must move in
+//! lockstep on both sides.
+
+mod model;
+
+pub use model::{
+    parse_document, to_canonical_json, Extern, ExternParam, Function, HandleEntry, Lifetime,
+    LoweredDocument, Manifest, ManifestCase, Param, Rejected, Resource, ResourceMember, Stmt,
+    Surface, TypeShape, LOWERED_VERSION,
+};

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

@@ -0,0 +1,255 @@
+//! Typed model of the Layer 2 document and its manifest ledger.
+//!
+//! Field ORDER in every struct is normative: serde serializes declaration
+//! order, and the canonical emitter must reproduce `ownlang/lowered.py`'s
+//! construction order byte-for-byte. Optional keys exist in exactly two
+//! flavours, mirroring the Python emitter: fields Python always writes
+//! (possibly `null`) are `Option<T>` WITHOUT skip; the handle-entry allowlist
+//! keys Python writes only-when-present are `Option<T>` with
+//! `skip_serializing_if`.
+
+use serde::{Deserialize, Serialize};
+
+/// The Layer 2 surface version — must equal `ownlang/lowered.py`'s
+/// `LOWERED_VERSION` and `manifest.json`'s `lowered_version`.
+pub const LOWERED_VERSION: u32 = 1;
+
+/// One parsed golden: either a full lowered document or a fail-loud rejection.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Surface {
+    /// A lowered Module + handle map.
+    Lowered(LoweredDocument),
+    /// An `OwnIRError` rejection whose message text is part of the surface.
+    Rejected(Rejected),
+}
+
+/// `{"lowered_version": ..., "error": ...}` — a vocabulary-skew rejection.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Rejected {
+    pub lowered_version: u32,
+    pub error: String,
+}
+
+/// The full Layer 2 document (field order is the canonical JSON order).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct LoweredDocument {
+    pub lowered_version: u32,
+    pub module: String,
+    pub resources: Vec<Resource>,
+    pub externs: Vec<Extern>,
+    pub lifetimes: Vec<Lifetime>,
+    pub functions: Vec<Function>,
+    pub handles: Vec<HandleEntry>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Resource {
+    pub name: String,
+    /// Always present, possibly `null` (the human `[resource: ...]` tag).
+    pub kind: Option<String>,
+    pub members: Vec<ResourceMember>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ResourceMember {
+    pub role: String,
+    pub name: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Extern {
+    pub name: String,
+    pub params: Vec<ExternParam>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ExternParam {
+    pub effect: String,
+    #[serde(rename = "type")]
+    pub type_name: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Lifetime {
+    pub name: String,
+    /// The strictly-longer region, or `null` for a root region.
+    pub longer: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Function {
+    pub name: String,
+    /// The subscriber region, or `null` when no capture was minted.
+    pub lifetime: Option<String>,
+    pub params: Vec<Param>,
+    /// The synthesized owned return type, or `null` for a void body.
+    pub ret: Option<TypeShape>,
+    pub body: Vec<Stmt>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Param {
+    pub handle: String,
+    #[serde(rename = "type")]
+    pub type_shape: Option<TypeShape>,
+    pub line: i64,
+    pub lifetime: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct TypeShape {
+    pub name: String,
+    pub borrowed: bool,
+    pub mutable: bool,
+}
+
+/// The closed statement vocabulary under the `stmt` discriminator. Adding a
+/// variant is a Layer 2 contract change (version bump on both sides).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "stmt", rename_all = "snake_case", deny_unknown_fields)]
+pub enum Stmt {
+    Acquire {
+        handle: String,
+        resource: String,
+        line: i64,
+    },
+    Release {
+        handle: String,
+        line: i64,
+    },
+    Use {
+        handle: String,
+        line: i64,
+    },
+    Overspan {
+        handle: String,
+        line: i64,
+    },
+    Return {
+        /// `null` = a bare return (no owned value).
+        handle: Option<String>,
+        line: i64,
+    },
+    AliasJoin {
+        handle: String,
+        src: String,
+        line: i64,
+    },
+    Call {
+        callee: String,
+        args: Vec<String>,
+        line: i64,
+    },
+    Subscribe {
+        source: String,
+        line: i64,
+    },
+    If {
+        cond: String,
+        then: Vec<Self>,
+        #[serde(rename = "else")]
+        r#else: Vec<Self>,
+        line: i64,
+    },
+    While {
+        cond: String,
+        body: Vec<Self>,
+        line: i64,
+    },
+}
+
+/// One normalized handle-map entry: `handle` first, then the allowlist keys in
+/// fixed order, each present only when the underlying record carried it.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct HandleEntry {
+    pub handle: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub component: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub file: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub line: Option<i64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub event: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub handler: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub resource: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub released: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub source: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub source_type: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub di_source_life: Option<String>,
+    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
+    pub type_name: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ever_released: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub pool: Option<bool>,
+}
+
+/// `tests/fixtures/lowered/manifest.json` — the frozen case ledger.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Manifest {
+    pub comment: String,
+    pub lowered_version: u32,
+    pub cases: Vec<ManifestCase>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ManifestCase {
+    pub name: String,
+    pub rules: Vec<String>,
+    pub rust_replay: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub decision: Option<String>,
+}
+
+/// Parse one golden document, strictly typed.
+///
+/// A JSON object carrying `error` is a [`Rejected`], anything else must be a
+/// full [`LoweredDocument`] — unknown fields fail in both shapes, so a
+/// Python-side surface change cannot slip past the typed replay.
+///
+/// # Errors
+/// Returns the underlying `serde_json` error when the text is not valid JSON
+/// or does not match the closed Layer 2 shapes.
+pub fn parse_document(text: &str) -> Result<Surface, serde_json::Error> {
+    let value: serde_json::Value = serde_json::from_str(text)?;
+    if value.get("error").is_some() {
+        return serde_json::from_value::<Rejected>(value).map(Surface::Rejected);
+    }
+    serde_json::from_value::<LoweredDocument>(value).map(Surface::Lowered)
+}
+
+/// The canonical serialized form — byte-identical to the Python emitter's
+/// `render_lowered`: 2-space pretty JSON, declaration field order, raw UTF-8,
+/// one trailing newline.
+///
+/// # Errors
+/// Returns the underlying `serde_json` error if serialization fails (it
+/// cannot for these closed types, but the emitter refuses to panic).
+pub fn to_canonical_json(surface: &Surface) -> Result<String, serde_json::Error> {
+    let mut out = match surface {
+        Surface::Lowered(doc) => serde_json::to_string_pretty(doc)?,
+        Surface::Rejected(rej) => serde_json::to_string_pretty(rej)?,
+    };
+    out.push('\n');
+    Ok(out)
+}