cadmpeg-codec-sat 0.6.2

Inspect and decode bare ASM .sat/.sab/.smt/.smb B-rep streams.
Documentation
// SPDX-License-Identifier: Apache-2.0
//! SAT dialect identity: which registry row a bare stream is, and how it was
//! admitted.
//!
//! The `*LossCode` template: the enum is internal, registry-generated
//! [`DialectId`] constants are the boundary, [`classify`] is the one
//! construction path, and the vocabulary is closed.
//!
//! This module owns the primary `sat:` host layer. Each classified stream also
//! emits the non-primary `acis:` kernel layer owned by `cadmpeg-asm`.
//!
//! # Identity and admission are the host grammar
//!
//! The host rows are discriminated by the stream's leading bytes alone
//! ([`crate::detect::StreamKind`]), which are read exactly: `ASM BinaryFile4`/`8`, `ACIS
//! BinaryFile`, or the two text header lines. A recognized stream that has no
//! binary record-stream boundary or complete text framing takes
//! [`Admission::Refused`]. Inspection reports that match, and decode returns
//! [`cadmpeg_core::CodecError::UnsupportedDialect`] carrying the same host and
//! kernel layers.
//!
//! The kernel save format is banded on the separate `acis:` layer. The Spatial
//! ACIS record decoders are verified against majors 217 and 218; the ASM record
//! decoders compare no save format at all. A stream outside the verified band
//! is not refused: its records are read with the verified band's grammar, which
//! is [`Admission::Unverified`] on that layer, and `using` names the verified
//! binary `acis:` row whose grammar was substituted. An ACIS text stream
//! outside that band has no declared text-band grammar to name and is
//! [`Admission::Residual`]. The recovery is charged as
//! [`SatLossCode::SourceDialectUnverified`] by [`dialect_loss`], on a result
//! that carries whatever those records decoded.
//!
//! [`layers`] classifies both layers once, so the report and result share the
//! same host and kernel decisions.
//!
//! [`SatLossCode::SourceDialectUnverified`]:
//!     crate::loss::SatLossCode::SourceDialectUnverified

use crate::{SAT_ACIS_BINARY, SAT_ASM_BINARY, SAT_TEXT};
use cadmpeg_asm::kernel_header::{BinaryHeader, KernelHeader};
use cadmpeg_asm::{acis_header, asm_header, sat};
use cadmpeg_core::dialect::{DialectId, DialectMatch};
use cadmpeg_ir::report::loss::LossNote;
use std::collections::BTreeMap;

use crate::loss::SatLossCode;

/// Key of the stream encoding in [`DialectMatch::declared`].
const DECLARED_ENCODING: &str = "encoding";
/// Key of the text stream's terminator line in [`DialectMatch::declared`].
/// Absent on the binary branches, which carry no terminator.
const DECLARED_TERMINATOR: &str = "terminator";

/// The text branch's evidence.
///
/// The terminator line selects the branch, and the header carries the save
/// format the ACIS branch is banded on. The band keys on the terminator, not on
/// the product family the header names. Outside the verified band, an ACIS
/// terminator has no declared text-band grammar to name as `using`.
pub(crate) struct TextEvidence<'a> {
    /// Branch the terminator line selected.
    pub(crate) branch: sat::Terminator,
    /// Kernel header the three text header lines carried.
    pub(crate) header: &'a KernelHeader,
}

/// Kernel family selected by binary magic or a text terminator.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum Family {
    Asm,
    Acis,
}

impl Family {
    pub(crate) const fn as_str(self) -> &'static str {
        match self {
            Self::Asm => "asm",
            Self::Acis => "acis",
        }
    }
}

impl From<sat::Terminator> for Family {
    fn from(value: sat::Terminator) -> Self {
        match value {
            sat::Terminator::Asm => Self::Asm,
            sat::Terminator::Acis => Self::Acis,
        }
    }
}

/// Where a binary stream's record stream begins.
///
/// Minted only by [`record_stream_start`], so a value of this type is the
/// witness that the bytes frame; the offset it carries is the one decode reads.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) struct RecordStreamStart(usize);

impl RecordStreamStart {
    /// The byte offset the record stream begins at.
    pub(crate) const fn offset(self) -> usize {
        self.0
    }
}

/// The record-stream boundary the family's header grammar finds, if any.
pub(crate) fn record_stream_start(
    bytes: &[u8],
    family: Family,
    header: &BinaryHeader,
) -> Option<RecordStreamStart> {
    let start = match family {
        Family::Asm => asm_header::record_stream_start_with_header(bytes, header),
        Family::Acis => acis_header::record_stream_start_with_header(bytes, header),
    }?;
    Some(RecordStreamStart(start))
}

/// Stream family, parsed header, and framing admission from the source bytes.
pub(crate) enum StreamEvidence<'a> {
    Binary {
        family: Family,
        header: &'a BinaryHeader,
        stream: Option<RecordStreamStart>,
    },
    Text(Option<TextEvidence<'a>>),
}

impl StreamEvidence<'_> {
    /// The host row this evidence identifies. Every variant is a reportable
    /// kind, so the id is total: unclassified streams never reach here.
    const fn dialect(&self) -> DialectId {
        match self {
            Self::Binary {
                family: Family::Asm,
                ..
            } => SAT_ASM_BINARY,
            Self::Binary {
                family: Family::Acis,
                ..
            } => SAT_ACIS_BINARY,
            Self::Text(_) => SAT_TEXT,
        }
    }
}

/// The host match: identity from the discriminant, admission from framing.
///
/// [`Admission::Refused`] here is structural and nothing else: the host
/// discriminant matched but the stream did not frame. Kernel-band admission is
/// owned by `cadmpeg_asm::dialect::classify` and cannot change this host state.
fn host(evidence: &StreamEvidence<'_>) -> DialectMatch {
    let dialect = evidence.dialect();
    match evidence {
        StreamEvidence::Binary {
            stream: Some(_), ..
        }
        | StreamEvidence::Text(Some(_)) => DialectMatch::admitted(dialect),
        StreamEvidence::Binary { stream: None, .. } | StreamEvidence::Text(None) => {
            DialectMatch::refused(dialect)
        }
    }
}

/// The recovery loss a match charges, if it recovered.
///
/// `Some` exactly when the kernel match reports [`Admission::Unverified`] or
/// [`Admission::Residual`]. A binary recovery names the substituted binary
/// row. A text recovery states that no declared text-band grammar was
/// available. The message is not the contract; the code is.
pub(crate) fn dialect_loss(matched: &DialectMatch) -> Option<LossNote> {
    cadmpeg_asm::dialect::unverified_message("the stream", matched)
        .map(|message| SatLossCode::SourceDialectUnverified.note(message))
}

/// Host-framing declarations, verbatim, under keys pinned above.
///
/// Kernel save format belongs only to the separate `acis:` match.
fn declared(evidence: &StreamEvidence<'_>) -> BTreeMap<cadmpeg_core::text::NonBlankString, String> {
    let mut declared = BTreeMap::new();
    match evidence {
        StreamEvidence::Binary { .. } => {
            declared.insert(
                cadmpeg_core::nonblank_const!(DECLARED_ENCODING),
                "binary".into(),
            );
        }
        StreamEvidence::Text(text) => {
            declared.insert(
                cadmpeg_core::nonblank_const!(DECLARED_ENCODING),
                "text".into(),
            );
            let Some(text) = text else { return declared };
            declared.insert(
                cadmpeg_core::nonblank_const!(DECLARED_TERMINATOR),
                terminator_line(text.branch).into(),
            );
        }
    }
    declared
}

/// The terminator line a text branch ends with.
pub(crate) const fn terminator_line(branch: sat::Terminator) -> &'static str {
    match branch {
        sat::Terminator::Asm => "End-of-ASM-data",
        sat::Terminator::Acis => "End-of-ACIS-data",
    }
}

/// Classifies one stream. The single construction path for a [`DialectMatch`]
/// in this codec, so a classification bug and the report can never disagree.
///
/// Identity is the row the leading discriminant satisfies; admission is
/// [`host`]. Kernel save-format identity and admission are not copied into
/// this host match.
fn classify(evidence: &StreamEvidence<'_>) -> DialectMatch {
    host(evidence).with_declared(declared(evidence))
}

/// Classify the same evidence as the shared non-primary kernel layer.
fn kernel_layer(evidence: &StreamEvidence<'_>) -> DialectMatch {
    let header = match evidence {
        StreamEvidence::Binary { family, header, .. } => match family {
            Family::Asm => cadmpeg_asm::dialect::KernelHeaderRef::Asm(header),
            Family::Acis => cadmpeg_asm::dialect::KernelHeaderRef::Acis(header),
        },
        StreamEvidence::Text(Some(text)) => match text.branch {
            sat::Terminator::Asm => cadmpeg_asm::dialect::KernelHeaderRef::TextAsm(text.header),
            sat::Terminator::Acis => cadmpeg_asm::dialect::KernelHeaderRef::TextAcis(text.header),
        },
        StreamEvidence::Text(None) => cadmpeg_asm::dialect::KernelHeaderRef::Unknown,
    };
    cadmpeg_asm::dialect::classify(header)
}

/// Classifies the host and kernel layers from one evidence value.
pub(crate) fn layers(evidence: &StreamEvidence<'_>) -> (DialectMatch, DialectMatch) {
    (classify(evidence), kernel_layer(evidence))
}

#[cfg(test)]
mod tests;