From 2f47400d255d546f411a64dfa95e8f503c5e20f2 Mon Sep 17 00:00:00 2001 From: Patrick_Audley Date: Fri, 20 Nov 2026 22:44:10 -0600 Subject: [PATCH 1/2] Stream documentation RDF into the native parser Write the existing ordered N-Quads through a bounded pipe and admit the frozen graph only after the renderer and parser succeed. Declare the empty graph explicitly and preserve the native parser diagnostic on early refusal. Principles 2, 4, and 7. --- crates/docs-model/src/rdf.rs | 394 ++++++++---------- crates/errors/src/abox.rs | 14 +- crates/errors/src/abox.tests.rs | 27 +- crates/pipeline/src/stages/docs_render.rs | 85 +++- .../pipeline/src/stages/docs_render.tests.rs | 59 ++- docs/PIPELINE_SPINE.md | 9 +- 6 files changed, 331 insertions(+), 257 deletions(-) diff --git a/crates/docs-model/src/rdf.rs b/crates/docs-model/src/rdf.rs index e9314825b4..1327a27543 100644 --- a/crates/docs-model/src/rdf.rs +++ b/crates/docs-model/src/rdf.rs @@ -13,7 +13,7 @@ //! through GTS fold without bnode relabeling, sorted iteration over the //! already-sorted model collections, and a trailing newline. -use std::fmt::Write as _; +use std::io::{self, Write}; use crate::coverage::{CoverageContext, DIMENSIONS, slice_covered_dims, term_coverage}; use crate::maturity::{ @@ -114,11 +114,23 @@ pub fn to_gmeow_rdf( model: &DocsModel, entailments: &BTreeMap>, ) -> String { - let graph = format!("<{DOCUMENTATION_GRAPH}>"); - let mut lines = String::new(); + let mut bytes = Vec::new(); + write_gmeow_rdf(model, entailments, &mut bytes).expect("writing to a Vec cannot fail"); + String::from_utf8(bytes).expect("formatted RDF is UTF-8") +} - let triple = |s: &str, p: &str, o: &str, lines: &mut String| { - writeln!(lines, "{s} <{p}> {o} {graph} .").expect("writing to a String cannot fail"); +/// Write the documentation projection described by [`to_gmeow_rdf`] in row order. +/// +/// # Errors +/// +/// Returns the first output error. +pub fn write_gmeow_rdf( + model: &DocsModel, + entailments: &BTreeMap>, + lines: &mut W, +) -> io::Result<()> { + let triple = |s: &str, p: &str, o: &str, lines: &mut W| { + writeln!(lines, "{s} <{p}> {o} <{DOCUMENTATION_GRAPH}> .") }; let literal = |value: &str| format!("\"{}\"", nq_escape(value)); let prose = |value: &str| format!("{}@{}", literal(value), gmeow_errors::abox::X_GMEOW_ENGLISH); @@ -130,7 +142,7 @@ pub fn to_gmeow_rdf( // staying genuinely self-describing (the validator requires the box role and // a provenance link on every materialized individual). The shared // `gmeow_errors::abox::annotate_nquads` adapter supplies these annotations. - let annotate = |subject: &str, label: &str, definition: &str, lines: &mut String| { + let annotate = |subject: &str, label: &str, definition: &str, lines: &mut W| { // Every caller here already formats `subject` bracketed (``) for its // OTHER triples in the same block; the shared adapter takes the bare IRI // and re-brackets it itself, so strip the brackets back off here rather @@ -142,7 +154,7 @@ pub fn to_gmeow_rdf( definition, DOCUMENTATION_GRAPH, lines, - ); + ) }; // The coarse-grain provenance shared by every documented term's @@ -187,38 +199,38 @@ pub fn to_gmeow_rdf( &subject, RDF_TYPE, &format!("<{GMEOW}DocumentedTerm>"), - &mut lines, - ); + lines, + )?; triple( &subject, &format!("{GMEOW}documents"), &format!("<{}>", term.iri), - &mut lines, - ); + lines, + )?; triple( &subject, &format!("{GMEOW}docCategory"), &literal(category_name(term.category)), - &mut lines, - ); + lines, + )?; triple( &subject, &format!("{GMEOW}docHasDefinition"), &boolean(term.definition.is_some()), - &mut lines, - ); + lines, + )?; triple( &subject, &format!("{GMEOW}docUrl"), &literal(&format!("terms/{slug}/index.html")), - &mut lines, - ); + lines, + )?; triple( &subject, &format!("{GMEOW}docOwnerSlice"), &format!("<{}>", term.owner_slice), - &mut lines, - ); + lines, + )?; // Per-term native-reasoner status — projected ONLY when a verdict is // attached (the production docs-graph stage consumes stage-reason), so the // SPARQL surface never carries a fabricated satisfiability claim. A class @@ -229,8 +241,8 @@ pub fn to_gmeow_rdf( &subject, &format!("{GMEOW}docReasoningStatus"), &literal(status), - &mut lines, - ); + lines, + )?; } annotate( &subject, @@ -240,8 +252,8 @@ pub fn to_gmeow_rdf( term.iri, category_name(term.category) ), - &mut lines, - ); + lines, + )?; // Searchable content facets — the REAL display label, definition, advisory // prose, and crosswalk tokens (NOT the meta `annotate` label), so an offline @@ -256,23 +268,23 @@ pub fn to_gmeow_rdf( &subject, &format!("{GMEOW}docSearchLabel"), &prose(term.label.as_deref().unwrap_or(&term.curie)), - &mut lines, - ); + lines, + )?; if let Some(definition) = &term.definition { triple( &subject, &format!("{GMEOW}docSearchDefinition"), &prose(definition), - &mut lines, - ); + lines, + )?; } for advice in term_advice_facet(term) { triple( &subject, &format!("{GMEOW}docSearchAdvice"), &prose(&advice), - &mut lines, - ); + lines, + )?; } if let Some(tokens) = alignment_facets.get(term.iri.as_str()) { for token in tokens { @@ -280,8 +292,8 @@ pub fn to_gmeow_rdf( &subject, &format!("{GMEOW}docSearchAlignment"), &literal(token), - &mut lines, - ); + lines, + )?; } } @@ -296,11 +308,11 @@ pub fn to_gmeow_rdf( &real, GMEOW_DEFINITION_DIGEST, &literal(&term.content_digest), - &mut lines, - ); + lines, + )?; } if let Some(version) = &term.added_in_version { - triple(&real, GMEOW_ADDED_IN_VERSION, &literal(version), &mut lines); + triple(&real, GMEOW_ADDED_IN_VERSION, &literal(version), lines)?; } for entry in &term.changelog { let identity = format!( @@ -318,13 +330,13 @@ pub fn to_gmeow_rdf( entry.source.wire(), identity_digest ); - triple(&real, GMEOW_HAS_CHANGELOG_ENTRY, &entry_iri, &mut lines); + triple(&real, GMEOW_HAS_CHANGELOG_ENTRY, &entry_iri, lines)?; triple( &entry_iri, RDF_TYPE, &format!("<{GMEOW_CHANGELOG_ENTRY}>"), - &mut lines, - ); + lines, + )?; // A changelog entry is generated A-Box instance data like every other doc // subject: annotate it (label / definition / provenance anchor / gmeow:boxABox // role) so the folded bundle satisfies the assertional-tier validation contract @@ -344,16 +356,16 @@ pub fn to_gmeow_rdf( entry.version, term.iri ) }), - &mut lines, - ); + lines, + )?; triple( &entry_iri, GMEOW_ENTRY_VERSION, &literal(&entry.version), - &mut lines, - ); + lines, + )?; if let Some(note) = &entry.note { - triple(&entry_iri, GMEOW_ENTRY_NOTE, &literal(note), &mut lines); + triple(&entry_iri, GMEOW_ENTRY_NOTE, &literal(note), lines)?; } } @@ -371,71 +383,61 @@ pub fn to_gmeow_rdf( // validation contract. for ev in term_evidence(model, term, provenance.as_ref()) { let ev_iri = format!("<{GMEOW}documentation/evidence/{slug}/{}>", ev.kind); - triple( - &ev_iri, - RDF_TYPE, - &format!("<{GMEOW}DocEvidence>"), - &mut lines, - ); + triple(&ev_iri, RDF_TYPE, &format!("<{GMEOW}DocEvidence>"), lines)?; triple( &ev_iri, &format!("{GMEOW}docEvidenceKind"), &format!("<{GMEOW}docEvidenceKind{}>", ev.kind_suffix), - &mut lines, - ); + lines, + )?; triple( &ev_iri, &format!("{GMEOW}documents"), &format!("<{}>", term.iri), - &mut lines, - ); + lines, + )?; triple( &ev_iri, &format!("{GMEOW}docClaim"), &prose(&ev.claim), - &mut lines, - ); + lines, + )?; // The grounding edge is mandatory and never empty — the fail-fast // grounding invariant (see `tests/doc_evidence.rs`). for grounded in &ev.grounded { - triple( - &ev_iri, - &format!("{GMEOW}docGroundedBy"), - grounded, - &mut lines, - ); + triple(&ev_iri, &format!("{GMEOW}docGroundedBy"), grounded, lines)?; } if let Some((_, chain)) = &provenance { triple( &ev_iri, &format!("{GMEOW}docProducedByChain"), &literal(chain), - &mut lines, - ); + lines, + )?; } if let Some(judgment) = &ev.judgment { triple( &ev_iri, &format!("{GMEOW}docJudgment"), &literal(judgment), - &mut lines, - ); + lines, + )?; } for (predicate, value) in &ev.int_props { triple( &ev_iri, &format!("{GMEOW}{predicate}"), &integer(*value), - &mut lines, - ); + lines, + )?; } for (predicate, value) in &ev.digest_props { triple( &ev_iri, &format!("{GMEOW}{predicate}"), &format!("{}^^<{GMEOW}blake3_256Digest>", literal(value)), - &mut lines, - ); + lines, + )?; } annotate( &ev_iri, @@ -444,8 +446,8 @@ pub fn to_gmeow_rdf( "{} documentation evidence for {} — {}.", ev.kind, term.iri, ev.claim ), - &mut lines, - ); + lines, + )?; } // Per-term documentation-coverage incidence: for each of the seventeen @@ -470,8 +472,8 @@ pub fn to_gmeow_rdf( &subject, &format!("{GMEOW}{predicate}"), &format!("<{GMEOW}{}>", dim.dimension.local_name()), - &mut lines, - ); + lines, + )?; } } @@ -489,8 +491,8 @@ pub fn to_gmeow_rdf( &format!("<{}>", creator.subject()), creator.predicate().as_str(), &object, - &mut lines, - ); + lines, + )?; } let slug = slice_slug(slice); let subject = format!("<{GMEOW}documentation/slice/{slug}>"); @@ -498,26 +500,26 @@ pub fn to_gmeow_rdf( &subject, RDF_TYPE, &format!("<{GMEOW}DocumentedSlice>"), - &mut lines, - ); + lines, + )?; triple( &subject, &format!("{GMEOW}documents"), &format!("<{}>", slice.iri), - &mut lines, - ); + lines, + )?; triple( &subject, &format!("{GMEOW}docUrl"), &literal(&format!("slices/{slug}/index.html")), - &mut lines, - ); + lines, + )?; annotate( &subject, &format!("Documentation entry: slice {slug}"), &format!("Documentation projection for slice {}.", slice.iri), - &mut lines, - ); + lines, + )?; // The slice's REAL display name as a searchable facet (the site // `search-index.json` indexes the same `slice_display`), so `docs_search` // can surface a slice record by its title/label. A slice carries no @@ -526,8 +528,8 @@ pub fn to_gmeow_rdf( &subject, &format!("{GMEOW}docSearchLabel"), &prose(&slice_display(slice)), - &mut lines, - ); + lines, + )?; // Per-slice documentation-coverage incidence + FCA-derived maturity. The // slice's covered-dimension set is its concept intent over ALL nineteen @@ -547,8 +549,8 @@ pub fn to_gmeow_rdf( &subject, &format!("{GMEOW}{predicate}"), &format!("<{GMEOW}{}>", dim.local_name()), - &mut lines, - ); + lines, + )?; } // The bounded coverage fraction against the FULL anchor's intent — the // reference floor (`asserted-or-Full`; no per-slice asserted maturity is @@ -562,8 +564,8 @@ pub fn to_gmeow_rdf( &subject, &format!("{GMEOW}coverageFraction"), &decimal(fraction), - &mut lines, - ); + lines, + )?; // The FCA-derived earned floor: the largest anchor whose intent ⊆ the // slice's covered set. Emitted ONLY when an anchor is earned (an honest // absence otherwise) — deterministic next-closure over the incidence, never @@ -573,8 +575,8 @@ pub fn to_gmeow_rdf( &subject, &format!("{GMEOW}docEarnedMaturity"), &format!("<{GMEOW}{}>", anchor.local_name()), - &mut lines, - ); + lines, + )?; } } @@ -599,42 +601,37 @@ pub fn to_gmeow_rdf( &subject, RDF_TYPE, &format!("<{GMEOW}DocumentedDocument>"), - &mut lines, - ); + lines, + )?; triple( &subject, &format!("{GMEOW}documents"), &format!("<{}>", doc.slice_iri), - &mut lines, - ); + lines, + )?; triple( &subject, &format!("{GMEOW}docSourcePath"), &literal(&doc.source_path), - &mut lines, - ); + lines, + )?; triple( &subject, &format!("{GMEOW}docTitle"), &prose(&doc.title), - &mut lines, - ); + lines, + )?; triple( &subject, &format!("{GMEOW}docRawDigest"), &format!("{}^^<{GMEOW}sha256Digest>", literal(&doc.raw_digest)), - &mut lines, - ); + lines, + )?; // The RESOLVED page location — the resolver projection. `page_of` // returns the trailing-slash page path the `SourceToPageMap` minted; // the top-level `docs.md` resolves to its slice page. if let Some(page) = page_map.page_of(&doc.slice_iri, &doc.source_path) { - triple( - &subject, - &format!("{GMEOW}docUrl"), - &literal(page), - &mut lines, - ); + triple(&subject, &format!("{GMEOW}docUrl"), &literal(page), lines)?; } annotate( &subject, @@ -643,8 +640,8 @@ pub fn to_gmeow_rdf( "Documentation page for `{}` in slice {}.", doc.source_path, doc.slice_iri ), - &mut lines, - ); + lines, + )?; } } @@ -656,26 +653,26 @@ pub fn to_gmeow_rdf( &subject, RDF_TYPE, &format!("<{GMEOW}DocumentedConcern>"), - &mut lines, - ); + lines, + )?; triple( &subject, &format!("{GMEOW}documents"), &format!("<{}>", concern.iri), - &mut lines, - ); + lines, + )?; triple( &subject, &format!("{GMEOW}docUrl"), &literal(&format!("concerns/{slug}/index.html")), - &mut lines, - ); + lines, + )?; annotate( &subject, &format!("Documentation entry: concern {slug}"), &format!("Documentation projection for concern {}.", concern.iri), - &mut lines, - ); + lines, + )?; // The concern's REAL display name (and definition, when authored) as // searchable facets — the same fields the site `search-index.json` indexes // for a concern record. @@ -683,15 +680,15 @@ pub fn to_gmeow_rdf( &subject, &format!("{GMEOW}docSearchLabel"), &prose(&concern_display(concern)), - &mut lines, - ); + lines, + )?; if let Some(definition) = &concern.definition { triple( &subject, &format!("{GMEOW}docSearchDefinition"), &prose(definition), - &mut lines, - ); + lines, + )?; } } @@ -704,26 +701,26 @@ pub fn to_gmeow_rdf( &subject, RDF_TYPE, &format!("<{GMEOW}DocumentedMappingSet>"), - &mut lines, - ); + lines, + )?; triple( &subject, &format!("{GMEOW}documents"), &format!("<{}>", set.iri), - &mut lines, - ); + lines, + )?; triple( &subject, &format!("{GMEOW}docUrl"), &literal("linkages/index.html"), - &mut lines, - ); + lines, + )?; annotate( &subject, &format!("Documentation entry: mapping set {slug}"), &format!("Documentation projection for mapping set {}.", set.iri), - &mut lines, - ); + lines, + )?; } // ── Fixture bodies (first-class, term-keyed) ───────────────────────────── @@ -749,12 +746,7 @@ pub fn to_gmeow_rdf( .map(|t| (t.curie.as_str(), t.iri.as_str())) .collect(); for (subject, f) in &fixture_subjects { - triple( - subject, - RDF_TYPE, - &format!("<{GMEOW}DocFixture>"), - &mut lines, - ); + triple(subject, RDF_TYPE, &format!("<{GMEOW}DocFixture>"), lines)?; // One `gmeow:documents` edge per referenced DOCUMENTED term (the // reference list is CURIEs; resolve each to its real term IRI so the edge // lands on the term node, never a CURIE literal). A referenced term that @@ -765,8 +757,8 @@ pub fn to_gmeow_rdf( subject, &format!("{GMEOW}documents"), &format!("<{}>", iri), - &mut lines, - ); + lines, + )?; } } // The well-formed / counter-example kind as an enumerated individual @@ -779,37 +771,37 @@ pub fn to_gmeow_rdf( subject, &format!("{GMEOW}docFixtureKind"), &format!("<{GMEOW}docFixtureKind{kind_suffix}>"), - &mut lines, - ); + lines, + )?; triple( subject, &format!("{GMEOW}docFixtureText"), &literal(&f.text), - &mut lines, - ); + lines, + )?; if let Some(outcome) = &f.expected_outcome { triple( subject, &format!("{GMEOW}docExpectedOutcome"), &literal(outcome), - &mut lines, - ); + lines, + )?; } if let Some(code) = &f.violation_code { triple( subject, &format!("{GMEOW}docViolationCode"), &literal(code), - &mut lines, - ); + lines, + )?; } for object in fixture_rationale_objects(model, f) { triple( subject, crate::model::conformance::RATIONALE, &object, - &mut lines, - ); + lines, + )?; } // Mandatory grounding: the owning slice IRI is the honest truthmaker (the // slice's tests/ tree is where the fixture body lives). @@ -817,8 +809,8 @@ pub fn to_gmeow_rdf( subject, &format!("{GMEOW}docGroundedBy"), &format!("<{}>", f.slice), - &mut lines, - ); + lines, + )?; annotate( subject, &format!("Conformance fixture: {}", f.title), @@ -828,8 +820,8 @@ pub fn to_gmeow_rdf( f.slice, kind_suffix.to_ascii_lowercase() ), - &mut lines, - ); + lines, + )?; } // ── Competency questions (query text + expected rows, first-class) ─────── @@ -845,16 +837,16 @@ pub fn to_gmeow_rdf( &subject, RDF_TYPE, &format!("<{GMEOW}DocumentedCompetency>"), - &mut lines, - ); + lines, + )?; // Mandatory grounding: the real competency-question IRI the record is a // projection of. triple( &subject, &format!("{GMEOW}docGroundedBy"), &format!("<{}>", comp.iri), - &mut lines, - ); + lines, + )?; // One `gmeow:documents` edge per exercised term (exercises is // sorted/deduped in the model). for term_iri in &comp.exercises { @@ -862,94 +854,79 @@ pub fn to_gmeow_rdf( &subject, &format!("{GMEOW}documents"), &format!("<{term_iri}>"), - &mut lines, - ); + lines, + )?; } if let Some(query) = &comp.query_text { triple( &subject, &format!("{GMEOW}cqQueryText"), &literal(query), - &mut lines, - ); + lines, + )?; } if let Some(count) = comp.expected_row_count { triple( &subject, &format!("{GMEOW}cqExpectRowCount"), &integer(count), - &mut lines, - ); + lines, + )?; } if let Some(exact) = comp.exact_rows { triple( &subject, &format!("{GMEOW}cqExactRows"), &boolean(exact), - &mut lines, - ); + lines, + )?; } for rationale in &comp.rationales { let value = purrdf::TermValue::from_rdf_term(&purrdf::RdfTerm::Literal(rationale.clone())); let mut object = String::new(); purrdf_core::write_term_value(&value, &mut object); - triple( - &subject, - &format!("{GMEOW}cqRationale"), - &object, - &mut lines, - ); + triple(&subject, &format!("{GMEOW}cqRationale"), &object, lines)?; } // The enumerated expected result rows, each a first-class node carrying // its per-variable cells — so the expected result set is queryable content, // not just a count. Rows arrive in the model's deterministic order. for (i, row) in comp.expected_rows.iter().enumerate() { let row_iri = format!("<{GMEOW}documentation/competency/{comp_slug}/row/{i}>"); - triple( - &subject, - &format!("{GMEOW}cqExpectedRow"), - &row_iri, - &mut lines, - ); + triple(&subject, &format!("{GMEOW}cqExpectedRow"), &row_iri, lines)?; triple( &row_iri, RDF_TYPE, &format!("<{GMEOW}CompetencyExpectedRow>"), - &mut lines, - ); + lines, + )?; for cell in &row.cells { if let Some(var) = &cell.var { - triple( - &row_iri, - &format!("{GMEOW}cqCellVar"), - &literal(var), - &mut lines, - ); + triple(&row_iri, &format!("{GMEOW}cqCellVar"), &literal(var), lines)?; } if let Some(value_iri) = &cell.value_iri { triple( &row_iri, &format!("{GMEOW}cqCellValueIri"), &format!("<{value_iri}>"), - &mut lines, - ); + lines, + )?; } if let Some(value_literal) = &cell.value_literal { triple( &row_iri, &format!("{GMEOW}cqCellValueLiteral"), &literal(value_literal), - &mut lines, - ); + lines, + )?; } } triple( &row_iri, &format!("{GMEOW}docGroundedBy"), &format!("<{}>", comp.iri), - &mut lines, - ); + lines, + )?; annotate( &row_iri, &format!("Expected row {i}: {}", comp.iri), @@ -957,8 +934,8 @@ pub fn to_gmeow_rdf( "Expected result row {i} of competency question {}.", comp.iri ), - &mut lines, - ); + lines, + )?; } annotate( &subject, @@ -967,8 +944,8 @@ pub fn to_gmeow_rdf( "Documentation projection of competency question {}.", comp.iri ), - &mut lines, - ); + lines, + )?; } // ── Entailment DAG (per-term reasoner derivations) ─────────────────────── @@ -982,45 +959,40 @@ pub fn to_gmeow_rdf( let term_slug_ent = iri_slug(term_iri); for (i, ent) in ents.iter().enumerate() { let ent_iri = format!("<{GMEOW}documentation/entailment/{term_slug_ent}/{i}>"); - triple( - &ent_iri, - RDF_TYPE, - &format!("<{GMEOW}Entailment>"), - &mut lines, - ); + triple(&ent_iri, RDF_TYPE, &format!("<{GMEOW}Entailment>"), lines)?; triple( &ent_iri, &format!("{GMEOW}documents"), &format!("<{term_iri}>"), - &mut lines, - ); + lines, + )?; triple( &ent_iri, &format!("{GMEOW}entailmentRule"), &literal(&ent.rule), - &mut lines, - ); + lines, + )?; triple( &ent_iri, &format!("{GMEOW}entailmentConclusion"), &literal(&ent.conclusion), - &mut lines, - ); + lines, + )?; for premise in &ent.premises { triple( &ent_iri, &format!("{GMEOW}entailmentPremise"), &literal(premise), - &mut lines, - ); + lines, + )?; } // Mandatory grounding: the documented term the derivation is about. triple( &ent_iri, &format!("{GMEOW}docGroundedBy"), &format!("<{term_iri}>"), - &mut lines, - ); + lines, + )?; annotate( &ent_iri, &format!("Entailment {i}: {term_iri}"), @@ -1028,12 +1000,12 @@ pub fn to_gmeow_rdf( "Reasoner entailment {i} about {term_iri}: {}.", ent.conclusion ), - &mut lines, - ); + lines, + )?; } } - lines + Ok(()) } fn fixture_rationale_objects( diff --git a/crates/errors/src/abox.rs b/crates/errors/src/abox.rs index 35faba5d44..705dd5ccef 100644 --- a/crates/errors/src/abox.rs +++ b/crates/errors/src/abox.rs @@ -20,7 +20,7 @@ //! language tag, never bare `en` — see `docs/GROUNDING.md` for why the carrier //! tag exists. -use std::fmt::Write as _; +use std::io::{self, Write}; use crate::render::nq_escape; @@ -110,13 +110,17 @@ pub fn abox_annotations( /// order of label, definition, isDefinedBy and graphBoxRole. Literals use /// [`nq_escape`] and carry the [`X_GMEOW_ENGLISH`] language tag. IRIs are /// angle-bracketed. +/// +/// # Errors +/// +/// Returns the writer's error if any annotation cannot be written. pub fn annotate_nquads( subject_iri: &str, label: &str, definition: &str, graph_iri: &str, - out: &mut String, -) { + out: &mut impl Write, +) -> io::Result<()> { for (predicate, object) in abox_annotations(subject_iri, label, definition, graph_iri) { let object_text = match object { AboxObject::Iri(iri) => format!("<{iri}>"), @@ -127,9 +131,9 @@ pub fn annotate_nquads( writeln!( out, "<{subject_iri}> <{predicate}> {object_text} <{graph_iri}> ." - ) - .expect("writing to a String cannot fail"); + )?; } + Ok(()) } /// Builder-flavor adapter: push the four A-Box annotation quads for diff --git a/crates/errors/src/abox.tests.rs b/crates/errors/src/abox.tests.rs index bbc1d5d4f0..0e631b0c21 100644 --- a/crates/errors/src/abox.tests.rs +++ b/crates/errors/src/abox.tests.rs @@ -8,12 +8,17 @@ const LABEL: &str = "Example subject"; const DEFINITION: &str = "A subject minted for a unit test."; const GRAPH: &str = "https://blackcatinformatics.ca/gmeow/graph/example"; +fn annotation_text(label: &str, definition: &str) -> String { + let mut bytes = Vec::new(); + annotate_nquads(SUBJECT, label, definition, GRAPH, &mut bytes).expect("write annotations"); + String::from_utf8(bytes).expect("annotations are UTF-8") +} + /// Exactly four triples, in the fixed (label, definition, isDefinedBy, /// graphBoxRole) order — the order both adapters commit to. #[test] fn annotate_nquads_emits_four_triples_in_fixed_order() { - let mut out = String::new(); - annotate_nquads(SUBJECT, LABEL, DEFINITION, GRAPH, &mut out); + let out = annotation_text(LABEL, DEFINITION); assert!( out.ends_with('\n'), "the final quad must end with a newline" @@ -42,8 +47,7 @@ fn annotate_nquads_emits_four_triples_in_fixed_order() { /// `graphBoxRole`'s object is exactly `gmeow:boxABox`. #[test] fn annotate_nquads_isdefinedby_and_role_objects_are_correct() { - let mut out = String::new(); - annotate_nquads(SUBJECT, LABEL, DEFINITION, GRAPH, &mut out); + let out = annotation_text(LABEL, DEFINITION); let out: Vec<_> = out.lines().collect(); assert!( out[2].contains(&format!("<{GRAPH}>")), @@ -61,8 +65,7 @@ fn annotate_nquads_isdefinedby_and_role_objects_are_correct() { /// language tag, never bare `en`. #[test] fn annotate_nquads_literals_carry_the_carrier_language_tag() { - let mut out = String::new(); - annotate_nquads(SUBJECT, LABEL, DEFINITION, GRAPH, &mut out); + let out = annotation_text(LABEL, DEFINITION); for line in out.lines().take(2) { assert!( line.ends_with(&format!("\"@{X_GMEOW_ENGLISH} <{GRAPH}> .")), @@ -78,10 +81,8 @@ fn annotate_nquads_literals_carry_the_carrier_language_tag() { /// Determinism: identical inputs produce byte-identical output, every call. #[test] fn annotate_nquads_is_deterministic() { - let mut a = String::new(); - let mut b = String::new(); - annotate_nquads(SUBJECT, LABEL, DEFINITION, GRAPH, &mut a); - annotate_nquads(SUBJECT, LABEL, DEFINITION, GRAPH, &mut b); + let a = annotation_text(LABEL, DEFINITION); + let b = annotation_text(LABEL, DEFINITION); assert_eq!(a, b); } @@ -90,8 +91,7 @@ fn annotate_nquads_is_deterministic() { /// N-Quads line shape (still four triples, still ending in the graph token). #[test] fn annotate_nquads_escapes_literal_content() { - let mut out = String::new(); - annotate_nquads(SUBJECT, "has \"quotes\"", "has\\backslash", GRAPH, &mut out); + let out = annotation_text("has \"quotes\"", "has\\backslash"); let out: Vec<_> = out.lines().collect(); assert!(out[0].contains("has \\\"quotes\\\""), "{}", out[0]); assert!(out[1].contains("has\\\\backslash"), "{}", out[1]); @@ -107,8 +107,7 @@ fn annotate_nquads_escapes_literal_content() { fn cross_substrate_parity_string_and_builder_emit_the_same_quad_set() { use std::collections::BTreeSet; - let mut lines = String::new(); - annotate_nquads(SUBJECT, LABEL, DEFINITION, GRAPH, &mut lines); + let lines = annotation_text(LABEL, DEFINITION); let mut builder = purrdf_core::RdfDatasetBuilder::new(); annotate_builder(&mut builder, SUBJECT, LABEL, DEFINITION, GRAPH).unwrap(); diff --git a/crates/pipeline/src/stages/docs_render.rs b/crates/pipeline/src/stages/docs_render.rs index eae7c9dd9f..90f82a812b 100644 --- a/crates/pipeline/src/stages/docs_render.rs +++ b/crates/pipeline/src/stages/docs_render.rs @@ -2,40 +2,90 @@ // SPDX-License-Identifier: AGPL-3.0-only //! Project the typed slice documentation model into `graph/documentation`. -//! The renderer's N-Quads are a transient input to native parsing. Snapshot +//! The renderer streams N-Quads to the native parser. Snapshot //! reads the frozen documentation graph from this stage's dataset. use std::collections::{BTreeMap, BTreeSet}; +use std::io::{self, BufRead, BufReader, BufWriter, PipeWriter, Write}; use std::path::Path; use std::sync::Arc; +use std::thread; use gmeow_docs::model::{ ConsistencyAssessment, ConstraintRule, DiagnosticsDigest, DocDiagFinding, DocsModel, ReasoningVerdict, }; -use gmeow_docs::rdf::to_gmeow_rdf; +use gmeow_docs::rdf::write_gmeow_rdf; use purrdf::{RdfDataset, RdfDatasetBuilder, RdfTerm}; use crate::node::{CachePolicy, Stage, StageInput, StageOutput, StageProduct}; use crate::stages::carrier::{GRAPH_DOCUMENTATION, require_rooted_graph}; const RDF_TYPE: &str = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"; +const STAGE: &str = "stage-docs-render"; /// Publish the already named graph the N-Quads renderer supplies. -fn admit_rendered_documentation(rendered: &str) -> gmeow_errors::Result> { - let dataset = if rendered.is_empty() { +fn admit_rendered_documentation( + mut rendered: impl BufRead, +) -> gmeow_errors::Result> { + let empty = rendered + .fill_buf() + .map_err(|source| documentation_io("read rendered N-Quads", source))? + .is_empty(); + let dataset = if empty { let mut builder = RdfDatasetBuilder::new(); let graph = builder.intern_iri(GRAPH_DOCUMENTATION)?; builder.declare_named_graph(graph)?; builder.freeze().map_err(gmeow_errors::Diag::from)? } else { - purrdf::parse_dataset(rendered.as_bytes(), "application/n-quads", None) + purrdf::parse_dataset_from_reader(rendered, "application/n-quads", None) .map_err(gmeow_errors::Diag::from)? }; - require_rooted_graph(&dataset, "stage-docs-render", GRAPH_DOCUMENTATION)?; + require_rooted_graph(&dataset, STAGE, GRAPH_DOCUMENTATION)?; Ok(dataset) } +fn documentation_io(operation: &str, source: io::Error) -> gmeow_errors::Diag { + gmeow_errors::Diag::of_kind(crate::error::StageFailed::caused_by( + STAGE.to_owned(), + format!("{operation}: {source}"), + source, + )) +} + +fn stream_documentation( + emit: impl FnOnce(&mut BufWriter) -> io::Result<()>, +) -> gmeow_errors::Result> { + let (reader, writer) = + io::pipe().map_err(|source| documentation_io("open the documentation RDF pipe", source))?; + thread::scope(|scope| { + let parser = thread::Builder::new() + .name("documentation-rdf-parser".into()) + .spawn_scoped(scope, move || { + admit_rendered_documentation(BufReader::new(reader)) + }) + .map_err(|source| documentation_io("start the documentation RDF parser", source))?; + let mut writer = BufWriter::new(writer); + let written = emit(&mut writer).and_then(|()| writer.flush()); + + // Close the writer before joining. Discard buffered bytes after a write + // failure so the destructor cannot retry them. + drop(writer.into_parts()); + let parsed = parser.join().unwrap_or_else(|_| { + Err(gmeow_errors::Diag::of_kind(crate::error::StageFailed { + stage: STAGE.to_owned(), + message: "documentation RDF parser thread panicked".into(), + cause: None, + })) + }); + match (written, parsed) { + (Err(write), Err(parse)) if write.kind() == io::ErrorKind::BrokenPipe => Err(parse), + (Err(source), _) => Err(documentation_io("write rendered N-Quads", source)), + (Ok(()), parsed) => parsed, + } + }) +} + /// Select the declared in-DAG reasoning owner. Post-DAG documentation explicitly /// selects its retained snapshot and uses the same native admission below. pub(crate) fn reasoning_verdict_from_reason( @@ -648,8 +698,8 @@ pub(crate) fn schema_fragments_from_json( /// Discover the docs model under `root`, attach the native-reasoner `verdict`, the /// diagnostics→term join digest, and the dynamic per-term projection-loss join -/// digest (all from `upstream`), and project it to the documentation named graph -/// (N-Quads). The verdict is required so the SPARQL surface always carries the +/// digest (all from `upstream`), and stream the N-Quads into the documentation +/// named graph. The verdict is required so the SPARQL surface always carries the /// per-term reasoning status (never a fabricated default); the diagnostics digest /// is required (hard-fails on a missing `stage-validate`/`stage-compile-logic` /// upstream product) so the per-term "Diagnostics you might hit" surface and any @@ -665,11 +715,11 @@ pub(crate) fn schema_fragments_from_json( /// `gmeow_docs::model::DocsModel::discover_with_manifest_and_catalog`, never the committed /// `generated/catalog/term-content-manifest.nq`, which lags one regenerate behind /// whenever a term's definition digest changes (the same stale-disk-fold class). -pub fn render_docs_graph( +fn render_docs_graph( root: &Path, verdict: ReasoningVerdict, upstream: &BTreeMap, -) -> Result { +) -> Result, gmeow_errors::Diag> { // The per-term content manifest, read off THIS run's stage-term-manifest product // (hard-fails on a missing artifact) — never the committed // generated/catalog/term-content-manifest.nq, which is the PREVIOUS run's bytes @@ -713,6 +763,7 @@ pub fn render_docs_graph( e, )) })?; + drop(catalog_bytes); model.attach_reasoning(verdict); let known_term_iris: BTreeSet = model.terms.iter().map(|t| t.iri.clone()).collect(); let diagnostics = @@ -735,7 +786,8 @@ pub fn render_docs_graph( // derivations (rule → conclusion, all premises) as first-class queryable RDF. let entailments = crate::stages::carrier::term_entailments_from_upstream(upstream, &known_term_iris)?; - Ok(to_gmeow_rdf(&model, &entailments)) + drop(known_term_iris); + stream_documentation(move |writer| write_gmeow_rdf(&model, &entailments, writer)) } /// Recursively collect every regular file under `dir` into `out` (fail-fast on a @@ -1060,12 +1112,11 @@ impl Stage for DocsRenderStage { } fn run(&self, input: StageInput<'_>) -> Result { let verdict = reasoning_verdict_from_reason(input.upstream)?; - let dataset = { - let graph = render_docs_graph(input.root, verdict, input.upstream)?; - crate::node::measure_stage_phase(self.id(), "parse-documentation-rdf", || { - admit_rendered_documentation(&graph) - })? - }; + let dataset = crate::node::measure_stage_phase( + self.id(), + "render-and-parse-documentation-rdf", + || render_docs_graph(input.root, verdict, input.upstream), + )?; Ok(StageOutput::new(StageProduct::from_artifacts_over( self.id(), dataset, diff --git a/crates/pipeline/src/stages/docs_render.tests.rs b/crates/pipeline/src/stages/docs_render.tests.rs index 5d0a0277aa..dabcd019ff 100644 --- a/crates/pipeline/src/stages/docs_render.tests.rs +++ b/crates/pipeline/src/stages/docs_render.tests.rs @@ -17,13 +17,16 @@ fn documentation_admission_preserves_stage_and_snapshot_identity() { }], ..Default::default() }; - let rendered = to_gmeow_rdf(&model, &BTreeMap::new()); + let entailments = BTreeMap::new(); + let rendered = gmeow_docs::rdf::to_gmeow_rdf(&model, &entailments); assert!(!rendered.is_empty(), "the renderer emits a documented term"); let reified = format!( "_:doc \"A document\"@en <{GRAPH_DOCUMENTATION}> .\n\ + <{GRAPH_DOCUMENTATION}> .\n\ \ <<( _:doc \"A document\"@en )>> <{GRAPH_DOCUMENTATION}> .\n\ - <{GRAPH_DOCUMENTATION}> .\n" + \"{detail}\" <{GRAPH_DOCUMENTATION}> .\n", + detail = "é".repeat(16_384), ); let snapshot_id = |dataset: &RdfDataset| { let mut snapshot = purrdf::gts_compose::SnapshotBuilder::new(); @@ -38,8 +41,18 @@ fn documentation_admission_preserves_stage_and_snapshot_identity() { .digest }; - for input in [rendered.as_str(), reified.as_str(), ""] { - let admitted = admit_rendered_documentation(input).expect("admit the rendered graph"); + for (input, admitted) in [ + ( + rendered.as_str(), + stream_documentation(|writer| write_gmeow_rdf(&model, &entailments, writer)), + ), + ( + reified.as_str(), + stream_documentation(|writer| writer.write_all(reified.as_bytes())), + ), + ("", stream_documentation(|_| Ok(()))), + ] { + let admitted = admitted.expect("admit the rendered graph"); assert_eq!( admitted.owned_named_graphs().collect::>(), [RdfTerm::iri(GRAPH_DOCUMENTATION)] @@ -64,11 +77,47 @@ fn documentation_admission_refuses_foreign_graph_rows() { " .", ] { let input = format!(" <{GRAPH_DOCUMENTATION}> .\n{foreign}\n"); - let error = admit_rendered_documentation(&input).expect_err("refuse misplaced RDF"); + let error = stream_documentation(|writer| writer.write_all(input.as_bytes())) + .expect_err("refuse misplaced RDF"); assert!(error.message().contains(GRAPH_DOCUMENTATION)); } } +/// Accept a graph only after the renderer and parser have both finished successfully. +#[test] +fn documentation_stream_refuses_partial_writer_output() { + let error = stream_documentation(|writer| { + writeln!(writer, " <{GRAPH_DOCUMENTATION}> .")?; + writer.flush()?; + Err(io::Error::other( + "documentation writer failed after a valid row", + )) + }) + .expect_err("a valid prefix cannot be published after a writer failure"); + assert!( + error + .message() + .contains("documentation writer failed after a valid row") + ); +} + +/// An early parser refusal must release the blocked writer and preserve the RDF diagnostic. +#[test] +fn documentation_stream_keeps_parser_refusal_on_broken_pipe() { + use std::io::Read as _; + + let invalid = b"invalid N-Quads\n"; + let expected = admit_rendered_documentation(invalid.as_slice()) + .expect_err("the native parser refuses the invalid row"); + let error = stream_documentation(|writer| { + writer.write_all(invalid)?; + io::copy(&mut io::repeat(b'x').take(2 * 1024 * 1024), writer)?; + Ok(()) + }) + .expect_err("parser refusal prevents publication"); + assert_eq!(error.message(), expected.message()); +} + fn repo_root() -> std::path::PathBuf { Path::new(env!("CARGO_MANIFEST_DIR")) .join("..") diff --git a/docs/PIPELINE_SPINE.md b/docs/PIPELINE_SPINE.md index 708383690b..07742e34a1 100644 --- a/docs/PIPELINE_SPINE.md +++ b/docs/PIPELINE_SPINE.md @@ -103,9 +103,7 @@ Stage kinds (source-load, transform, reason, validate, docs-render) differ only deliver by attaching to the carrier. `stage-docs-render` publishes `graph/documentation` in its frozen dataset. -The documentation projector appends each row and its shared A-Box annotations -to one N-Quads buffer and releases that text after native parsing. Snapshot -selects the named graph through the declared dataset edge. +Snapshot selects the named graph through the declared dataset edge. `stage-parse-sources` owns the original native root, module and import document parses. Its typed source catalog retains exact source receipts, document bases, @@ -215,8 +213,9 @@ input blank scopes remain distinct. These producer inputs carry locations in the RDF and report payloads; unexpected physical row-location attachments fail admission before publication. Diagnostics retain their selected graph placement. -The documentation producer parses the renderer's named N-Quads and publishes -that native dataset. An empty render publishes the empty named graph. The +The documentation producer streams the renderer's named N-Quads through a +bounded pipe to the native parser. Both the renderer and parser must succeed +before publication. An empty render publishes the empty named graph. The producer and snapshot assembly both check that the documentation graph is the sole declaration and owns every ordinary statement, reifier and annotation. Snapshot assembly places the dataset as an independently scoped source. From 926b29b704311d791a20affdabb29ac0b6d2bcf8 Mon Sep 17 00:00:00 2001 From: Patrick_Audley Date: Fri, 20 Nov 2026 23:06:29 -0600 Subject: [PATCH 2/2] Report typed failures from the N-Quads writers Return a registered N-Quads output diagnostic from each public writer and retain the original I/O cause. Preserve the parser refusal when it closes the pipe and the writer reports a broken pipe. Principles 2, 4, and 7. --- crates/docs-model/src/rdf.rs | 9 ++-- crates/errors/src/abox.rs | 10 ++-- crates/errors/src/error.rs | 34 ++++++++++++-- crates/pipeline/src/stages/docs_render.rs | 16 +++++-- .../pipeline/src/stages/docs_render.tests.rs | 46 +++++++++++++------ 5 files changed, 87 insertions(+), 28 deletions(-) diff --git a/crates/docs-model/src/rdf.rs b/crates/docs-model/src/rdf.rs index 1327a27543..cb3c0a8967 100644 --- a/crates/docs-model/src/rdf.rs +++ b/crates/docs-model/src/rdf.rs @@ -13,7 +13,9 @@ //! through GTS fold without bnode relabeling, sorted iteration over the //! already-sorted model collections, and a trailing newline. -use std::io::{self, Write}; +use std::io::Write; + +use gmeow_errors::error::NQuadsWriteFailure; use crate::coverage::{CoverageContext, DIMENSIONS, slice_covered_dims, term_coverage}; use crate::maturity::{ @@ -123,14 +125,15 @@ pub fn to_gmeow_rdf( /// /// # Errors /// -/// Returns the first output error. +/// Returns [`NQuadsWriteFailure`] with the original writer error as its cause. pub fn write_gmeow_rdf( model: &DocsModel, entailments: &BTreeMap>, lines: &mut W, -) -> io::Result<()> { +) -> gmeow_errors::Result<()> { let triple = |s: &str, p: &str, o: &str, lines: &mut W| { writeln!(lines, "{s} <{p}> {o} <{DOCUMENTATION_GRAPH}> .") + .map_err(NQuadsWriteFailure::diagnostic) }; let literal = |value: &str| format!("\"{}\"", nq_escape(value)); let prose = |value: &str| format!("{}@{}", literal(value), gmeow_errors::abox::X_GMEOW_ENGLISH); diff --git a/crates/errors/src/abox.rs b/crates/errors/src/abox.rs index 705dd5ccef..f6c244f549 100644 --- a/crates/errors/src/abox.rs +++ b/crates/errors/src/abox.rs @@ -20,8 +20,9 @@ //! language tag, never bare `en` — see `docs/GROUNDING.md` for why the carrier //! tag exists. -use std::io::{self, Write}; +use std::io::Write; +use crate::error::NQuadsWriteFailure; use crate::render::nq_escape; /// The GMEOW namespace IRI prefix. @@ -113,14 +114,14 @@ pub fn abox_annotations( /// /// # Errors /// -/// Returns the writer's error if any annotation cannot be written. +/// Returns [`NQuadsWriteFailure`] with the original writer error as its cause. pub fn annotate_nquads( subject_iri: &str, label: &str, definition: &str, graph_iri: &str, out: &mut impl Write, -) -> io::Result<()> { +) -> crate::Result<()> { for (predicate, object) in abox_annotations(subject_iri, label, definition, graph_iri) { let object_text = match object { AboxObject::Iri(iri) => format!("<{iri}>"), @@ -131,7 +132,8 @@ pub fn annotate_nquads( writeln!( out, "<{subject_iri}> <{predicate}> {object_text} <{graph_iri}> ." - )?; + ) + .map_err(NQuadsWriteFailure::diagnostic)?; } Ok(()) } diff --git a/crates/errors/src/error.rs b/crates/errors/src/error.rs index ce3dbf896b..08d2ddc103 100644 --- a/crates/errors/src/error.rs +++ b/crates/errors/src/error.rs @@ -1,7 +1,7 @@ // SPDX-FileCopyrightText: 2026 Blackcat Informatics® Inc. // SPDX-License-Identifier: AGPL-3.0-only -//! Substrate-model diagnostic kinds. +//! Diagnostic kinds for the substrate model and its RDF output. //! //! Parsing a user/tool-supplied [`Severity`] or //! [`FindingCategory`] wire label is a HARD @@ -11,6 +11,8 @@ //! stable registered [`Code`], a [`Grade`], and staying downcastable off the //! [`Diag`](crate::diag::Diag) source. +use std::sync::Arc; + use crate::code::Code; use crate::grade::{Grade, Severity, Standpoint}; use crate::model::FindingCategory; @@ -35,18 +37,42 @@ crate::define_diag_kind! { message = "unknown finding category `{}`; expected one of the ten logic:FindingCategory wire values", value; } -/// The complete `gmeow-errors` model diagnostic-code catalog, in registration +crate::define_diag_kind! { + /// The destination refused an N-Quads write or flush. + pub struct NQuadsWriteFailure { cause: Arc } + code = "errors.rdf.nquads-write"; + grade = Grade::new(Severity::Error, FindingCategory::ModelingDisciplineViolation, Standpoint::Binding); + message = "write N-Quads output: {}", cause; + source = failure => Some(failure.cause.as_ref()); +} + +impl NQuadsWriteFailure { + /// Report the refusal while preserving its original I/O error. + #[must_use] + pub fn diagnostic(cause: std::io::Error) -> crate::Diag { + crate::Diag::of_kind(Self { + cause: Arc::new(cause), + }) + } +} + +/// The complete `gmeow-errors` diagnostic-code catalog, in registration /// order. Every [`DiagKind`](crate::diag::DiagKind) minted here appears once — /// [`register_all`] seeds them and the collision test proves the code strings are /// distinct. -pub const ERRORS_DIAG_CODES: &[&str] = &[UnknownSeverityLabel::CODE, UnknownFindingCategory::CODE]; +pub const ERRORS_DIAG_CODES: &[&str] = &[ + UnknownSeverityLabel::CODE, + UnknownFindingCategory::CODE, + NQuadsWriteFailure::CODE, +]; -/// Eagerly intern every `gmeow-errors` model diagnostic code, seeding the +/// Eagerly intern every `gmeow-errors` diagnostic code, seeding the /// process-wide code registry. Idempotent (each `register()` is a `LazyLock`). pub fn register_all() -> Vec { vec![ UnknownSeverityLabel::register(), UnknownFindingCategory::register(), + NQuadsWriteFailure::register(), ] } diff --git a/crates/pipeline/src/stages/docs_render.rs b/crates/pipeline/src/stages/docs_render.rs index 90f82a812b..a68277519a 100644 --- a/crates/pipeline/src/stages/docs_render.rs +++ b/crates/pipeline/src/stages/docs_render.rs @@ -16,6 +16,7 @@ use gmeow_docs::model::{ ReasoningVerdict, }; use gmeow_docs::rdf::write_gmeow_rdf; +use gmeow_errors::error::NQuadsWriteFailure; use purrdf::{RdfDataset, RdfDatasetBuilder, RdfTerm}; use crate::node::{CachePolicy, Stage, StageInput, StageOutput, StageProduct}; @@ -54,7 +55,7 @@ fn documentation_io(operation: &str, source: io::Error) -> gmeow_errors::Diag { } fn stream_documentation( - emit: impl FnOnce(&mut BufWriter) -> io::Result<()>, + emit: impl FnOnce(&mut BufWriter) -> gmeow_errors::Result<()>, ) -> gmeow_errors::Result> { let (reader, writer) = io::pipe().map_err(|source| documentation_io("open the documentation RDF pipe", source))?; @@ -66,7 +67,8 @@ fn stream_documentation( }) .map_err(|source| documentation_io("start the documentation RDF parser", source))?; let mut writer = BufWriter::new(writer); - let written = emit(&mut writer).and_then(|()| writer.flush()); + let written = + emit(&mut writer).and_then(|()| writer.flush().map_err(NQuadsWriteFailure::diagnostic)); // Close the writer before joining. Discard buffered bytes after a write // failure so the destructor cannot retry them. @@ -79,8 +81,14 @@ fn stream_documentation( })) }); match (written, parsed) { - (Err(write), Err(parse)) if write.kind() == io::ErrorKind::BrokenPipe => Err(parse), - (Err(source), _) => Err(documentation_io("write rendered N-Quads", source)), + (Err(write), Err(parse)) + if write + .downcast_ref::() + .is_some_and(|failure| failure.cause.kind() == io::ErrorKind::BrokenPipe) => + { + Err(parse) + } + (Err(write), _) => Err(write), (Ok(()), parsed) => parsed, } }) diff --git a/crates/pipeline/src/stages/docs_render.tests.rs b/crates/pipeline/src/stages/docs_render.tests.rs index dabcd019ff..0bbc693749 100644 --- a/crates/pipeline/src/stages/docs_render.tests.rs +++ b/crates/pipeline/src/stages/docs_render.tests.rs @@ -48,7 +48,11 @@ fn documentation_admission_preserves_stage_and_snapshot_identity() { ), ( reified.as_str(), - stream_documentation(|writer| writer.write_all(reified.as_bytes())), + stream_documentation(|writer| { + writer + .write_all(reified.as_bytes()) + .map_err(NQuadsWriteFailure::diagnostic) + }), ), ("", stream_documentation(|_| Ok(()))), ] { @@ -77,8 +81,12 @@ fn documentation_admission_refuses_foreign_graph_rows() { " .", ] { let input = format!(" <{GRAPH_DOCUMENTATION}> .\n{foreign}\n"); - let error = stream_documentation(|writer| writer.write_all(input.as_bytes())) - .expect_err("refuse misplaced RDF"); + let error = stream_documentation(|writer| { + writer + .write_all(input.as_bytes()) + .map_err(NQuadsWriteFailure::diagnostic) + }) + .expect_err("refuse misplaced RDF"); assert!(error.message().contains(GRAPH_DOCUMENTATION)); } } @@ -87,17 +95,26 @@ fn documentation_admission_refuses_foreign_graph_rows() { #[test] fn documentation_stream_refuses_partial_writer_output() { let error = stream_documentation(|writer| { - writeln!(writer, " <{GRAPH_DOCUMENTATION}> .")?; - writer.flush()?; - Err(io::Error::other( - "documentation writer failed after a valid row", - )) + writeln!(writer, " <{GRAPH_DOCUMENTATION}> .") + .map_err(NQuadsWriteFailure::diagnostic)?; + writer.flush().map_err(NQuadsWriteFailure::diagnostic)?; + let mut full: &mut [u8] = &mut []; + gmeow_errors::abox::annotate_nquads( + "urn:s", + "Subject", + "A documented subject.", + GRAPH_DOCUMENTATION, + &mut full, + ) }) .expect_err("a valid prefix cannot be published after a writer failure"); - assert!( + assert_eq!( error - .message() - .contains("documentation writer failed after a valid row") + .downcast_ref::() + .expect("N-Quads writer diagnostic") + .cause + .kind(), + io::ErrorKind::WriteZero, ); } @@ -110,8 +127,11 @@ fn documentation_stream_keeps_parser_refusal_on_broken_pipe() { let expected = admit_rendered_documentation(invalid.as_slice()) .expect_err("the native parser refuses the invalid row"); let error = stream_documentation(|writer| { - writer.write_all(invalid)?; - io::copy(&mut io::repeat(b'x').take(2 * 1024 * 1024), writer)?; + writer + .write_all(invalid) + .map_err(NQuadsWriteFailure::diagnostic)?; + io::copy(&mut io::repeat(b'x').take(2 * 1024 * 1024), writer) + .map_err(NQuadsWriteFailure::diagnostic)?; Ok(()) }) .expect_err("parser refusal prevents publication");