Skip to main content

convert_rs/
engine.rs

1//! Adapter registry, route execution, and per-step output validation.
2//!
3//! Every step receives a private output directory, and every artifact an adapter
4//! returns is checked: regular file, inside its step directory, declared
5//! format matches the step target, and total bytes respect the budget. A step
6//! that fails validation abandons the route and the engine tries the next.
7//! The workspace is a file ownership boundary, not an execution sandbox.
8
9use std::collections::{BTreeMap, BTreeSet};
10use std::io::Read;
11use std::path::{Path, PathBuf};
12use std::sync::Arc;
13
14use tempfile::TempDir;
15
16use crate::{
17    Adapter, Artifact, BackendStatus, ContentKind, ContentProfile, ConversionKind, Error, Format,
18    Graph, Limits, Plan, Policy, Result, StepRequest,
19};
20
21use crate::builtin::{BuiltinAdapter, detect};
22
23#[cfg(feature = "archives")]
24use crate::archives::ArchivesAdapter;
25#[cfg(feature = "media")]
26use crate::media::MediaAdapter;
27
28/// Per-conversion identification and route-selection choices.
29///
30/// Defaults use file identification and normal planning without a backend filter
31/// or quality params. Resource budgets are configured separately through
32/// [`Converter::limits`]. All fields are public; construct with
33/// `ConversionOptions { field: value, ..ConversionOptions::default() }`.
34#[derive(Clone, Debug, Default)]
35pub struct ConversionOptions {
36    /// Override format identification for every input (a format ID or extension).
37    ///
38    /// Skips content identification, including its empty-file rejection. Staging
39    /// still requires regular files within the per-file input budget. This is a
40    /// caller assertion, not a content validation request.
41    pub from: Option<String>,
42    /// Require every executed step to use this backend.
43    ///
44    /// Normal planning first finds a bounded set of routes, then filters it; a
45    /// matching route outside that set is not searched for. Identity plans have
46    /// no steps and pass any backend filter. Forced plans are checked step by step.
47    pub backend: Option<String>,
48    /// Skip route search and attempt only this caller-supplied plan.
49    ///
50    /// Prefer a plan obtained from [`Converter::plan`]. Steps must have concrete
51    /// format IDs. Execution checks kind gates, the `external` flag against
52    /// [`Policy::allow_external`], backend filtering, format continuity, and
53    /// returned artifacts. It does not verify edge membership in the graph,
54    /// recompute cost, enforce search budgets or decode-only gates, or apply
55    /// [`Policy::allow_external_packaging`]. Metadata is trusted: forced plans
56    /// are not a safe boundary for untrusted callers.
57    pub forced_plan: Option<Plan>,
58    /// Quality knobs forwarded verbatim to every executed step.
59    ///
60    /// The reserved key `quality` carries a 0-100 integer string; the engine
61    /// validates that range and adapters map it onto their closest encoder
62    /// control (JPEG/WebP quality, ffmpeg `-q`, imageMagick `-quality`).
63    /// Unknown keys are ignored by adapters, so passing knobs for a backend
64    /// that is not selected is harmless. Params never select paths or tools:
65    /// values are opaque strings and are never interpolated into argv as
66    /// executable or filesystem locations.
67    pub params: BTreeMap<String, String>,
68    /// Re-sniff every step's artifacts by content magic before accepting them.
69    ///
70    /// When enabled, the engine reads the first bytes of each returned file and
71    /// compares the detected format with the step target. A contradiction fails
72    /// the route and the engine falls back to the next plan. Bytes with no known
73    /// signature are accepted, because absence of evidence is not evidence of
74    /// a mismatch. Disabled by default because detection only covers formats
75    /// with registered signatures.
76    pub verify: bool,
77    /// Request a genuine re-encode when source and target formats match.
78    ///
79    /// By default a same-format request stages a byte-for-byte copy with an
80    /// empty plan. When set, planning searches for nonempty routes that return
81    /// to the requested format (image recompression, codec change inside a
82    /// container) and the identity copy is not offered. If no re-encode route
83    /// exists with the registered adapters, conversion fails with an explanatory
84    /// [`Error::Invalid`] rather than silently copying.
85    pub reencode: bool,
86    /// Content properties every executed step must declare it preserves.
87    ///
88    /// Names are adapter vocabulary (`pixels`, `alpha`, `metadata`, `structure`,
89    /// ...), matched case-insensitively against [`crate::Conversion::retained`] during
90    /// planning and enforced again for forced plans at execution. An empty list
91    /// (the default) adds no requirement. The zero-step identity copy satisfies
92    /// any retention request because it preserves bytes.
93    pub preserve: Vec<String>,
94    /// Ask adapters to inspect this input's content before planning.
95    ///
96    /// When set (and no [`Self::from`] override is given), [`Converter::convert`]
97    /// profiles the first identified input through [`Converter::profile`] and
98    /// searches with [`Graph::routes_with_profile`](convert_rs_core::Graph::routes_with_profile),
99    /// so edges with [`crate::Conversion::requires`] content are gated on the
100    /// observed streams. With an override, format identification (and any
101    /// inspection) is the caller's job and no profile is taken. The converter's
102    /// [`Policy::inspect_content`] sets the same behavior for every request;
103    /// this field overrides it per call.
104    pub inspect_content: bool,
105}
106
107impl ConversionOptions {
108    /// Validate caller-supplied params, returning a descriptive error.
109    ///
110    /// # Errors
111    ///
112    /// Returns [`Error::Invalid`] when `quality` is present but not an integer
113    /// within 0-100, or when `reencode` is combined with a forced plan.
114    fn validate(&self) -> Result<()> {
115        if let Some(quality) = self.params.get("quality") {
116            let value: u8 = quality
117                .trim()
118                .parse()
119                .map_err(|_| Error::Invalid(format!("quality must be 0-100, got {quality}")))?;
120            if value > 100 {
121                return Err(Error::Invalid(format!(
122                    "quality must be 0-100, got {value}"
123                )));
124            }
125        }
126        if self.reencode && self.forced_plan.is_some() {
127            return Err(Error::Invalid(
128                "reencode replaces route search and cannot combine with a forced plan".into(),
129            ));
130        }
131        if self.inspect_content && self.forced_plan.is_some() {
132            return Err(Error::Invalid(
133                "inspect_content drives route search and cannot combine with a forced plan".into(),
134            ));
135        }
136        Ok(())
137    }
138
139    /// Enforce requested retention claims on a caller-supplied forced plan.
140    ///
141    /// Search applies [`Policy::retain`] pruning, but forced plans bypass search,
142    /// so every nonempty step must declare it preserves at least the properties
143    /// named in [`Self::preserve`] (matched case-insensitively). Plans with no
144    /// steps are identity copies and always satisfy the request.
145    fn check_forced_retention(&self, plan: &Plan) -> Result<()> {
146        for step in &plan.steps {
147            for wanted in &self.preserve {
148                let wanted = wanted.trim().to_ascii_lowercase();
149                if wanted.is_empty() {
150                    continue;
151                }
152                if !step.retained.iter().any(|held| held == &wanted) {
153                    return Err(Error::Security(format!(
154                        "step {} via {} does not declare it preserves {wanted}",
155                        step.operation, step.backend
156                    )));
157                }
158            }
159        }
160        Ok(())
161    }
162
163    /// Enforce the caller's content policy on a caller-supplied forced plan.
164    ///
165    /// Mirrors the planner's [`Policy::require`] gate: each required kind must
166    /// appear in the observed profile (when one exists), in the final step's
167    /// [`crate::Conversion::produces`] claim, or in the target format's declared
168    /// payloads when [`Policy::require_content`] is off.
169    fn check_forced_content(
170        &self,
171        plan: &Plan,
172        target: &Format,
173        profile: Option<&ContentProfile>,
174        require: &[ContentKind],
175        require_content: bool,
176    ) -> Result<()> {
177        for wanted in require {
178            let delivered = profile
179                .filter(|found| found.format == target.id)
180                .is_some_and(|found| found.declares(wanted))
181                || plan
182                    .produced()
183                    .iter()
184                    .any(|produced| wanted.matches(produced))
185                || (!require_content
186                    && target
187                        .payloads
188                        .iter()
189                        .any(|declared| wanted.matches(declared)));
190            if !delivered {
191                return Err(Error::Security(format!(
192                    "forced plan does not deliver required content {wanted} in {target}",
193                    target = target.id
194                )));
195            }
196        }
197        Ok(())
198    }
199}
200
201/// One attempted route during a single [`Converter::convert`] call.
202///
203/// The report's `attempts` list records every route try in order, including the
204/// successful one, so callers can explain to users why a preferred route was
205/// skipped instead of silently falling back.
206#[derive(Clone, Debug)]
207#[non_exhaustive]
208pub struct RouteAttempt {
209    /// Zero-based position of this attempt in the fallback order.
210    pub index: usize,
211    /// Human-readable rendering of the route, e.g. `txt→json via builtin`.
212    pub route: String,
213    /// Adapter-declared plan that was executed (or attempted).
214    pub plan: Plan,
215    /// Rendered failure for rejected routes; `None` for the accepted route.
216    pub error: Option<String>,
217}
218
219impl RouteAttempt {
220    /// Construct an attempt record.
221    #[must_use]
222    pub fn new(index: usize, route: String, plan: Plan, error: Option<String>) -> Self {
223        Self {
224            index,
225            route,
226            plan,
227            error,
228        }
229    }
230}
231
232/// An informational warning derived from an executed step's declared kind.
233///
234/// The engine emits one warning for each non-lossless step of the successful
235/// route, including packaging and extraction. It does not measure actual loss
236/// or collect every adapter diagnostic. Failed attempts' warnings are discarded.
237#[derive(Clone, Debug, PartialEq, Eq)]
238pub struct Warning {
239    /// Zero-based index into the successful report's plan, not an artifact index.
240    pub step: usize,
241    /// Adapter that executed the step.
242    pub backend: String,
243    /// Adapter operation ID.
244    pub operation: String,
245    /// Adapter-declared semantic classification of the step.
246    pub kind: ConversionKind,
247    /// Explanation suitable for logs or a user interface.
248    pub message: String,
249}
250
251/// A resolved conversion: the accepted route, its warnings, and the artifacts.
252///
253/// Artifacts live in a private directory owned by this report. Dropping the
254/// report deletes them, so copy final files out before the report is dropped.
255/// Moving or cloning artifact paths does not transfer workspace ownership.
256/// Use [`Self::write_all_to`] to persist artifacts, or [`Self::directory`] to
257/// access the workspace directly.
258#[derive(Debug)]
259#[non_exhaustive]
260pub struct ConversionReport {
261    workspace: TempDir,
262    /// Route selected and executed by the converter, or the supplied forced plan.
263    pub plan: Plan,
264    /// Final artifacts, in adapter output order, or input order for identity copies.
265    ///
266    /// Format labels were checked against the target, not independently decoded,
267    /// unless [`ConversionOptions::verify`] was enabled for this conversion.
268    pub artifacts: Vec<Artifact>,
269    /// One warning per non-lossless step in this report's plan.
270    ///
271    /// An empty list is not a guarantee of complete quality or metadata preservation.
272    pub warnings: Vec<Warning>,
273    /// Cost-ordered notes for every non-lossless step that actually ran,
274    /// carrying the adapter-declared fidelity note when the step supplied one.
275    ///
276    /// This is the quality/cost view a UI should render next to warnings:
277    /// what each lossy step discards, straight from the adapter, rather than
278    /// the engine's generic sentence.
279    pub costs: Vec<StepCost>,
280    /// Structured log of every route attempted while producing this report.
281    ///
282    /// Every attempt is included, including earlier fallbacks that failed and
283    /// the accepted route (the final entry). Empty only when conversion itself
284    /// failed before planning, because a failed [`Converter::convert`] returns
285    /// [`Error::RoutesFailed`] only as a rendered string.
286    pub attempts: Vec<RouteAttempt>,
287    /// Requested [`ConversionOptions::params`] keys no executed step declared support for.
288    ///
289    /// Adapters ignore unknown keys by contract, so a typo would otherwise
290    /// silently change nothing. After each successful route the engine unions
291    /// [`crate::Adapter::param_keys`] over its steps and reports the difference.
292    /// A nonempty list is informational: the conversion succeeded, but those
293    /// knobs had no effect.
294    pub ignored_params: Vec<String>,
295}
296
297/// How reachable a requested target format is from a probed source format.
298#[derive(Clone, Debug, PartialEq, Eq)]
299pub enum CapabilityReason {
300    /// A route exists under the current policy and adapter availability.
301    Planned {
302        /// Cost of the cheapest found route.
303        cost: u64,
304    },
305    /// A route exists but the policy gate (lossy, bridges, external, ...) blocks it.
306    PolicyBlocked,
307    /// The only routes need backends that are not registered or report unavailable.
308    BackendUnavailable {
309        /// Backend names that exist but are unusable on this host.
310        backends: Vec<String>,
311    },
312    /// No graph route exists with the registered adapters under any gate setting.
313    NoRoute,
314}
315
316/// One target format's reachability from a source format.
317#[derive(Clone, Debug, PartialEq, Eq)]
318pub struct TargetCapability {
319    /// Resolved target format ID.
320    pub format: String,
321    /// Why or whether conversion to this format is currently possible.
322    pub reason: CapabilityReason,
323}
324
325/// Identification plus per-format deep-decode results for one input file.
326#[derive(Clone, Debug)]
327#[non_exhaustive]
328pub struct InputReport {
329    /// Identification found for the file.
330    pub identification: Identification,
331    /// Path checked.
332    pub path: PathBuf,
333    /// Formats whose registered adapters confirmed the file decodes.
334    ///
335    /// Populated by [`Converter::probe`] only for formats adapters answered
336    /// about; absence means no adapter gave an opinion, which is not rejection.
337    pub decodable_as: Vec<String>,
338}
339
340/// Where a [`Converter::profile`] profile came from.
341#[derive(Clone, Copy, Debug, PartialEq, Eq)]
342pub enum ProfileSource {
343    /// An available adapter described the file's streams.
344    Observed,
345    /// No claiming adapter answered; planning falls back to declared payloads.
346    NoOpinion,
347    /// An adapter's inspection exceeded [`Limits::timeout`] and nobody answered.
348    Timeout,
349}
350
351/// Identification plus an optional content profile for one input file.
352///
353/// Returned by [`Converter::profile`]. `profile` is `Some` only when an
354/// adapter actually described the file: an observed profile with no streams is
355/// real evidence (the file carries nothing describable), while `None` means no
356/// adapter answered and the graph's declared [`Format::payloads`] stand in.
357/// [`Self::identification`] is the [`Converter::identify`] result the profile
358/// was taken for.
359#[derive(Clone, Debug)]
360#[non_exhaustive]
361pub struct ProfileReport {
362    /// Format identification for the file.
363    pub identification: Identification,
364    /// Adapter-observed profile, or `None` when nothing answered.
365    pub profile: Option<ContentProfile>,
366    /// Which kind of outcome produced [`Self::profile`].
367    pub source: ProfileSource,
368}
369
370/// A note explaining what an executed step costs or discards.
371#[derive(Clone, Debug)]
372#[non_exhaustive]
373pub struct StepCost {
374    /// Zero-based step index in the executed plan.
375    pub step: usize,
376    /// Adapter that ran the step.
377    pub backend: String,
378    /// Adapter operation ID.
379    pub operation: String,
380    /// Adapter-declared semantic classification.
381    pub kind: ConversionKind,
382    /// The step's declared cost contribution.
383    pub cost: u32,
384    /// Adapter-supplied fidelity sentence, falling back to an engine default.
385    pub note: String,
386}
387
388impl StepCost {
389    /// Build a cost note for one executed step.
390    #[must_use]
391    pub fn new(
392        step: usize,
393        backend: &str,
394        operation: &str,
395        kind: ConversionKind,
396        cost: u32,
397        note: Option<&str>,
398    ) -> Self {
399        Self {
400            step,
401            backend: backend.to_owned(),
402            operation: operation.to_owned(),
403            kind,
404            cost,
405            note: note
406                .unwrap_or("no fidelity note declared by this adapter")
407                .to_owned(),
408        }
409    }
410}
411
412impl ConversionReport {
413    /// The workspace directory holding this report's artifacts.
414    ///
415    /// It also contains staged inputs and intermediate outputs. The returned
416    /// path is valid only while this report's temporary directory exists; this
417    /// method does not persist or transfer ownership of that directory.
418    #[must_use]
419    pub fn directory(&self) -> &Path {
420        self.workspace.path()
421    }
422
423    /// Copy the final artifacts into `dir`, creating it when missing.
424    ///
425    /// Files are named from [`Self::suggested_names`] and never overwritten: an
426    /// existing destination gains a `-<n>` suffix, matching the collision naming
427    /// inside the batch itself. Each file is written through a temporary path
428    /// and renamed, so a failed copy leaves no partial output. Returns the
429    /// written paths in artifact order. The report keeps ownership of the
430    /// workspace; dropping the report does not remove these copies. Calling
431    /// this method twice persists a second, rename-deduplicated set.
432    ///
433    /// # Errors
434    ///
435    /// Returns [`Error::Io`] for filesystem failures.
436    pub fn write_all_to(&self, dir: &Path) -> Result<Vec<PathBuf>> {
437        std::fs::create_dir_all(dir)?;
438        let mut written = Vec::with_capacity(self.artifacts.len());
439        for name in self.suggested_names() {
440            let destination = unique_destination(dir, &name);
441            let artifact = &self.artifacts[written.len()];
442            let temporary = dir.join(format!(".convert-rs-{}.tmp", uuid_like(written.len())));
443            let result = (|| -> Result<()> {
444                std::fs::copy(&artifact.path, &temporary)?;
445                std::fs::rename(&temporary, &destination)?;
446                Ok(())
447            })();
448            if result.is_err() {
449                let _ = std::fs::remove_file(&temporary);
450            }
451            result?;
452            written.push(destination);
453        }
454        Ok(written)
455    }
456
457    /// Stable artifact file names, `converted-<index>.<target>`.
458    ///
459    /// The report does not retain input paths, so batch output directories get
460    /// positional names; rename after writing if the original basename matters.
461    /// Artifacts that carry an [`Artifact::logical_name`] instead suggest a
462    /// sanitized form of it, preserving the member names extraction produced.
463    #[must_use]
464    pub fn suggested_names(&self) -> Vec<String> {
465        self.artifacts
466            .iter()
467            .enumerate()
468            .map(|(index, artifact)| match &artifact.logical_name {
469                Some(name) => sanitize_suggested_name(name),
470                None => {
471                    let extension = artifact
472                        .format
473                        .chars()
474                        .filter(|c| c.is_ascii_lowercase() || c.is_ascii_digit())
475                        .collect::<String>();
476                    let extension = if extension.is_empty() {
477                        "bin"
478                    } else {
479                        &extension
480                    };
481                    format!("converted-{index}.{extension}")
482                }
483            })
484            .collect()
485    }
486}
487
488/// Choose a destination path that exists nowhere yet, appending `-<n>` on a clash.
489fn unique_destination(dir: &Path, name: &str) -> PathBuf {
490    let candidate = dir.join(name);
491    if !candidate.exists() {
492        return candidate;
493    }
494    let (stem, extension) = name.rsplit_once('.').unwrap_or((name, ""));
495    (1u32..)
496        .map(|index| {
497            if extension.is_empty() {
498                dir.join(format!("{stem}-{index}"))
499            } else {
500                dir.join(format!("{stem}-{index}.{extension}"))
501            }
502        })
503        .find(|renamed| !renamed.exists())
504        .unwrap_or(candidate)
505}
506
507/// A short, deterministic pseudo-unique token for temp file names.
508fn uuid_like(seed: usize) -> String {
509    use std::hash::{Hash, Hasher};
510    let mut hasher = std::collections::hash_map::DefaultHasher::new();
511    (std::process::id(), seed, std::time::SystemTime::now()).hash(&mut hasher);
512    format!("{:016x}", hasher.finish())
513}
514
515/// Reduce a logical name to one safe file-name component for persistence.
516fn sanitize_suggested_name(name: &str) -> String {
517    let basename = name.rsplit(['/', '\\']).next().unwrap_or(name);
518    let cleaned: String = basename
519        .chars()
520        .take(128)
521        .map(|c| {
522            if c.is_control() || matches!(c, ':' | '<' | '>' | '"' | '|' | '?' | '*' | '\0') {
523                '_'
524            } else {
525                c
526            }
527        })
528        .collect();
529    let trimmed = cleaned.trim_matches(['.', ' ']);
530    if trimmed.is_empty() {
531        "file".to_owned()
532    } else {
533        trimmed.to_owned()
534    }
535}
536
537/// A resolved input format with the evidence used to determine it.
538///
539/// Identification is a heuristic label, not proof that a decoder accepts the file.
540/// [`Converter::identify`] never returns [`IdentificationMethod::Override`]; that
541/// variant represents a source override applied internally during conversion.
542#[derive(Clone, Debug, PartialEq, Eq)]
543#[non_exhaustive]
544pub struct Identification {
545    /// Resolved format ID.
546    pub format: String,
547    /// Evidence used to identify the input.
548    pub method: IdentificationMethod,
549}
550
551impl Identification {
552    /// Construct an identification record.
553    #[must_use]
554    pub fn new(format: impl Into<String>, method: IdentificationMethod) -> Self {
555        Self {
556            format: format.into(),
557            method,
558        }
559    }
560}
561
562/// Evidence source used by [`Converter::identify`].
563#[derive(Clone, Copy, Debug, PartialEq, Eq)]
564pub enum IdentificationMethod {
565    /// Caller supplied the format override.
566    Override,
567    /// A single filename suffix matched a registered ID or extension alias.
568    Extension,
569    /// Up to the first 1,024 bytes matched a known signature for a registered format.
570    Magic,
571    /// No known signature or extension matched; the input is treated as binary.
572    Unknown,
573}
574
575/// Adapter registry, routing configuration, and file conversion entry point.
576///
577/// [`Self::new`] and [`Default`] register compiled-in pure-Rust adapters with
578/// default [`Policy`] and [`Limits`]. Native tools require explicit discovery
579/// (with the `external` feature) and policy opt-in. Execution requires a Tokio
580/// runtime; registration, lookup, and planning do not.
581///
582/// Plans describe format-level operations, not codec selection. A route can
583/// fail because of input contents or adapter limitations despite valid metadata.
584pub struct Converter {
585    graph: Graph,
586    adapters: BTreeMap<String, Arc<dyn Adapter>>,
587    order: Vec<String>,
588    policy: Policy,
589    limits: Limits,
590}
591
592impl std::fmt::Debug for Converter {
593    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
594        formatter
595            .debug_struct("Converter")
596            .field("adapters", &self.order)
597            .field("formats", &self.graph.formats().count())
598            .finish()
599    }
600}
601
602impl Default for Converter {
603    fn default() -> Self {
604        Self::new()
605    }
606}
607
608impl Converter {
609    /// Construct a converter with every compiled-in pure-Rust adapter.
610    ///
611    /// Always includes byte/text operations. Optional `data`, `media`, and
612    /// `archives` features add their operations. Does not probe native tools.
613    #[must_use]
614    pub fn new() -> Self {
615        let mut converter = Self {
616            graph: Graph::new(),
617            adapters: BTreeMap::new(),
618            order: Vec::new(),
619            policy: Policy::default(),
620            limits: Limits::default(),
621        };
622        let _ = converter.register(Arc::new(BuiltinAdapter));
623        #[cfg(feature = "media")]
624        {
625            let _ = converter.register(Arc::new(MediaAdapter));
626        }
627        #[cfg(feature = "archives")]
628        {
629            let _ = converter.register(Arc::new(ArchivesAdapter));
630        }
631        converter
632    }
633
634    /// Construct a converter and register native-tool adapters whose probes succeed.
635    ///
636    /// Available only with the `external` feature. Starts from [`Self::new`];
637    /// unavailable tools are omitted rather than returned as errors. Probes do
638    /// not establish that every advertised format or codec works for a file.
639    /// Native tools are invoked per operation, not kept running by discovery.
640    ///
641    /// The default policy still disallows external routes. Set
642    /// [`Policy::allow_external`] to use them. The library does not sandbox native
643    /// tools; use operating-system isolation for hostile inputs.
644    #[cfg(feature = "external")]
645    pub async fn discover() -> Self {
646        let mut converter = Self::new();
647        let adapters = crate::external::discover().await;
648        for adapter in adapters {
649            if adapter.status().available {
650                let _ = converter.register(adapter);
651            }
652        }
653        converter
654    }
655
656    /// Add an adapter. Registration by name is idempotent; re-registering the
657    /// same name replaces the previous adapter and rebuilds the graph.
658    ///
659    /// Formats from all adapters are registered before edges, allowing references
660    /// to other adapters' formats. No availability probe is required. Metadata
661    /// must remain stable across calls. Failed registration leaves the current
662    /// registry and graph unchanged.
663    ///
664    /// # Errors
665    ///
666    /// Returns [`Error::Invalid`] for an empty name, a name longer than 64 bytes,
667    /// no format declarations, more than 8,192 formats, or more than 1,000,000
668    /// conversions from the incoming adapter. Returns [`Error::Plan`] if the
669    /// rebuilt graph rejects format or edge metadata. Backend names in edges
670    /// are not checked against the adapter's registration name.
671    pub fn register(&mut self, adapter: Arc<dyn Adapter>) -> Result<()> {
672        let name = adapter.name().to_owned();
673        if name.is_empty() || name.len() > 64 {
674            return Err(Error::Invalid("invalid adapter name".into()));
675        }
676        let formats = adapter.formats();
677        let conversions = adapter.conversions();
678        if formats.is_empty() || formats.len() > 8192 || conversions.len() > 1_000_000 {
679            return Err(Error::Invalid("adapter registration rejected".into()));
680        }
681        // Rebuild from every registered adapter so a replacement never leaves
682        // edges whose backend no longer exists, and so a rejected registration
683        // cannot leave a converter with an emptied registry.
684        let mut previous = self.adapters.clone();
685        let mut ordered = self.order.clone();
686        ordered.retain(|existing| existing != &name);
687        ordered.push(name.clone());
688        previous.insert(name.clone(), Arc::clone(&adapter));
689        let mut graph = Graph::new();
690        for key in &ordered {
691            for format in previous[key].formats() {
692                graph.add_format(format).map_err(Error::Plan)?;
693            }
694        }
695        for key in &ordered {
696            for conversion in previous[key].conversions() {
697                graph.add_conversion(conversion).map_err(Error::Plan)?;
698            }
699        }
700        self.graph = graph;
701        self.adapters = previous;
702        self.order = ordered;
703        Ok(())
704    }
705
706    #[must_use]
707    /// Replace resource limits using builder-style ownership.
708    ///
709    /// Does not validate the values. See [`Limits`] for adapter-dependent checks
710    /// and the distinction between budgets and hard resource isolation.
711    pub fn limits(mut self, limits: Limits) -> Self {
712        self.limits = limits;
713        self
714    }
715
716    #[must_use]
717    /// Replace the routing and execution policy using builder-style ownership.
718    ///
719    /// The policy is not validated here; invalid search settings fail at planning.
720    pub fn with_policy(mut self, policy: Policy) -> Self {
721        self.policy = policy;
722        self
723    }
724
725    /// Replace the routing policy at runtime.
726    ///
727    /// Affects later conversions, including kind checks on forced plans. It does
728    /// not alter previously returned plans or validate the new policy immediately.
729    pub fn set_policy(&mut self, policy: Policy) {
730        self.policy = policy;
731    }
732
733    #[must_use]
734    /// Return the immutable route graph used by this converter.
735    ///
736    /// Use [`Self::register`] to contribute formats and conversions.
737    pub fn graph(&self) -> &Graph {
738        &self.graph
739    }
740
741    #[must_use]
742    /// Return the current routing policy.
743    pub fn policy(&self) -> &Policy {
744        &self.policy
745    }
746
747    #[must_use]
748    /// Clone all registered formats in ascending format-ID order.
749    ///
750    /// Includes custom registrations, not just compiled-in or discovered adapters.
751    /// Presence does not imply a permitted route or a working encoder.
752    pub fn formats(&self) -> Vec<Format> {
753        self.graph.formats().cloned().collect()
754    }
755
756    /// Return registered adapters' status reports in ascending backend-name order.
757    ///
758    /// Calls [`Adapter::status`], which may return cached probe results. Tools
759    /// omitted during discovery are not listed; status does not re-plan routes.
760    #[must_use]
761    pub fn backends(&self) -> Vec<BackendStatus> {
762        self.adapters
763            .values()
764            .map(|adapter| adapter.status())
765            .collect()
766    }
767
768    #[must_use]
769    /// Resolve a format ID or extension alias without inspecting a file.
770    ///
771    /// Trims whitespace, folds ASCII case, and accepts leading dots. IDs take
772    /// precedence over aliases; ambiguous aliases choose the smallest format ID.
773    /// Returns `None` for unknown values. Does not parse paths or MIME types.
774    pub fn resolve(&self, value: &str) -> Option<&Format> {
775        self.graph.resolve(value)
776    }
777
778    /// Identify one nonempty regular input file by extension, then signature.
779    ///
780    /// Multi-dot names strip every alphanumeric suffix (`archive.tar.gz` looks
781    /// up `tar.gz`, then `gz`). A recognized suffix wins without opening or
782    /// validating the contents. Otherwise, up to 1,024 bytes are read for
783    /// magic detection. Unknown content becomes `bin`; built-in conversion
784    /// from `bin` to text requires reinterpretation opt-in, but identity does not.
785    ///
786    /// Zero-byte files are rejected unless [`Policy::allow_empty_inputs`] is
787    /// enabled; with the policy open, empty inputs identify as `bin`.
788    ///
789    /// # Errors
790    ///
791    /// Returns [`Error::Invalid`] when metadata cannot be inspected or a needed
792    /// header read fails. Returns [`Error::Security`] for nonregular paths
793    /// (including symlinks) and for empty files under the default policy.
794    /// Input byte budgets are checked later during staging, not by this method.
795    pub fn identify(&self, path: &Path) -> Result<Identification> {
796        let metadata = std::fs::symlink_metadata(path)
797            .map_err(|_| Error::Invalid(format!("cannot inspect {}", path.display())))?;
798        if !metadata.file_type().is_file() {
799            return Err(Error::Security("input is not a regular file".into()));
800        }
801        if metadata.len() == 0 {
802            if !self.policy.allow_empty_inputs {
803                return Err(Error::Security("input is empty".into()));
804            }
805            return Ok(Identification {
806                format: "bin".into(),
807                method: IdentificationMethod::Unknown,
808            });
809        }
810        if let Some(id) = extensions_of(path)
811            .iter()
812            .find_map(|value| self.graph.resolve(value))
813        {
814            return Ok(Identification {
815                format: id.id.clone(),
816                method: IdentificationMethod::Extension,
817            });
818        }
819        let mut header = [0u8; 1024];
820        let mut file =
821            std::fs::File::open(path).map_err(|_| Error::Invalid("input is unreadable".into()))?;
822        let count = file
823            .read(&mut header)
824            .map_err(|_| Error::Invalid("input is unreadable".into()))?;
825        if let Some(id) = detect(&header[..count]).and_then(|name| self.graph.resolve(name)) {
826            return Ok(Identification {
827                format: id.id.clone(),
828                method: IdentificationMethod::Magic,
829            });
830        }
831        Ok(Identification {
832            format: "bin".into(),
833            method: IdentificationMethod::Unknown,
834        })
835    }
836
837    /// Identify a file, then ask available decoders what it really holds.
838    ///
839    /// Runs [`Self::identify`] first, then calls [`Adapter::accepts_input`] on
840    /// every format declared by an available adapter. Formats an adapter confirms
841    /// are listed in [`InputReport::decodable_as`]; formats nobody answered
842    /// about are absent, which is not a rejection. The full byte budget applies
843    /// per answer, so probing a large adversarial file costs at most one decode
844    /// per declared format.
845    ///
846    /// # Errors
847    ///
848    /// As [`Self::identify`].
849    pub fn probe(&self, path: &Path) -> Result<InputReport> {
850        let identification = self.identify(path)?;
851        let mut decodable = BTreeSet::new();
852        for adapter in self.adapters.values() {
853            if !adapter.status().available {
854                continue;
855            }
856            for format in adapter.formats() {
857                if decodable.contains(&format.id) {
858                    continue;
859                }
860                if adapter.accepts_input(path, &format.id, &self.limits) == Some(true) {
861                    decodable.insert(format.id);
862                }
863            }
864        }
865        Ok(InputReport {
866            identification,
867            path: path.to_path_buf(),
868            decodable_as: decodable.into_iter().collect(),
869        })
870    }
871
872    /// Identify a file, then ask one available adapter to describe its streams.
873    ///
874    /// [`Policy::inspect_content`] is a directive for engines like this one:
875    /// when it is set, [`Self::convert`] profiles the first identified input
876    /// before planning and routes through
877    /// [`Graph::routes_with_profile`](convert_rs_core::Graph::routes_with_profile).
878    /// This method performs that profiling step and describes the outcome.
879    ///
880    /// Runs [`Self::identify`], then asks available adapters that declare the
881    /// identified format, in registration order, for [`Adapter::inspect`]. The
882    /// first adapter answering `Ok(Some(profile))` whose `profile.format`
883    /// matches the identification wins. Adapters that decline (`Ok(None)`),
884    /// fail (`Err`), or claim a different format express no opinion; the engine
885    /// asks the next one. An inspection exceeding [`Limits::timeout`] is
886    /// abandoned and recorded.
887    ///
888    /// When nobody answered, [`ProfileReport::profile`] is `None`: planning
889    /// falls back to declared [`Format::payloads`] unless
890    /// [`Policy::require_content`] demands observed evidence.
891    ///
892    /// # Errors
893    ///
894    /// As [`Self::identify`]. Adapter failures and timeouts are reported
895    /// through [`ProfileReport::source`], never as an error.
896    pub async fn profile(&self, path: &Path) -> Result<ProfileReport> {
897        let identification = self.identify(path)?;
898        let (profile, timed_out) = self.inspect(path, &identification.format).await;
899        Ok(ProfileReport {
900            source: match (&profile, timed_out) {
901                (Some(_), _) => ProfileSource::Observed,
902                (None, true) => ProfileSource::Timeout,
903                (None, false) => ProfileSource::NoOpinion,
904            },
905            identification,
906            profile,
907        })
908    }
909
910    /// Ask declaring available adapters for a profile of `path` as `format`.
911    ///
912    /// Shared by [`Self::profile`] and [`Self::convert`]. Returns the first
913    /// well-formed observed profile plus whether any inspection timed out.
914    async fn inspect(&self, path: &Path, format: &str) -> (Option<ContentProfile>, bool) {
915        let mut timed_out = false;
916        for adapter in self.adapters.values() {
917            if !adapter.status().available {
918                continue;
919            }
920            if !adapter
921                .formats()
922                .into_iter()
923                .any(|declared| declared.id == format)
924            {
925                continue;
926            }
927            let job = adapter.inspect(path, format, &self.limits);
928            match tokio::time::timeout(self.limits.timeout, job).await {
929                Ok(Some(Ok(mut profile))) if profile.format == format => {
930                    profile.deduplicate();
931                    return (Some(profile), false);
932                }
933                Ok(_) => continue,
934                Err(_elapsed) => timed_out = true,
935            }
936        }
937        (None, timed_out)
938    }
939
940    /// Classify how reachable each target format is from a source format.
941    ///
942    /// A target is [`CapabilityReason::Planned`] when the current policy and
943    /// registered adapters route to it. Otherwise the method re-searches with
944    /// every gate open, once restricted to available backends and once without:
945    /// a route that only the open search finds is [`CapabilityReason::PolicyBlocked`],
946    /// one that needs a registered-but-unavailable or missing backend is
947    /// [`CapabilityReason::BackendUnavailable`], and a format nothing routes to
948    /// is [`CapabilityReason::NoRoute`]. Planning only; no files are read.
949    ///
950    /// # Errors
951    ///
952    /// Returns [`Error::Invalid`] for an unknown source or target format name.
953    pub fn capabilities(&self, source: &str, targets: &[String]) -> Result<Vec<TargetCapability>> {
954        let source = self
955            .graph
956            .resolve(source)
957            .ok_or_else(|| Error::Invalid(format!("unknown source format: {source}")))?
958            .id
959            .clone();
960        let available: Vec<String> = self
961            .adapters
962            .values()
963            .filter(|adapter| adapter.status().available)
964            .map(|adapter| adapter.name().to_owned())
965            .collect();
966        let unrestricted = Policy {
967            allow_bridges: true,
968            allow_lossy: true,
969            allow_reinterpret: true,
970            allow_packaging: true,
971            allow_external: true,
972            allow_external_packaging: true,
973            allow_decode_only: true,
974            reencode_same_format: true,
975            allow_creative: true,
976            ..self.policy.clone()
977        };
978        let mut reports = Vec::with_capacity(targets.len());
979        for target in targets {
980            let target = self
981                .graph
982                .resolve(target)
983                .ok_or_else(|| Error::Invalid(format!("unknown target format: {target}")))?
984                .id
985                .clone();
986            reports.push(TargetCapability {
987                reason: self.classify(&source, &target, &available, &unrestricted),
988                format: target,
989            });
990        }
991        Ok(reports)
992    }
993
994    fn classify(
995        &self,
996        source: &str,
997        target: &str,
998        available: &[String],
999        unrestricted: &Policy,
1000    ) -> CapabilityReason {
1001        if let Ok(plans) = self.graph.routes(source, target, &self.policy)
1002            && let Some(cheapest) = plans.iter().map(|plan| plan.cost).min()
1003        {
1004            return CapabilityReason::Planned { cost: cheapest };
1005        }
1006        let permissive_available = Policy {
1007            backends: available.to_vec(),
1008            ..unrestricted.clone()
1009        };
1010        if matches!(
1011            self.graph.routes(source, target, &permissive_available),
1012            Ok(plans) if !plans.is_empty()
1013        ) {
1014            return CapabilityReason::PolicyBlocked;
1015        }
1016        match self.graph.routes(source, target, unrestricted) {
1017            Ok(plans)
1018                if plans.iter().any(|plan| {
1019                    plan.steps
1020                        .iter()
1021                        .all(|step| available.iter().any(|backend| backend == &step.backend))
1022                }) =>
1023            {
1024                CapabilityReason::PolicyBlocked
1025            }
1026            Ok(plans) => {
1027                let mut missing: Vec<String> = plans
1028                    .iter()
1029                    .flat_map(|plan| plan.steps.iter())
1030                    .map(|step| step.backend.clone())
1031                    .filter(|backend| !available.contains(backend))
1032                    .collect();
1033                missing.sort();
1034                missing.dedup();
1035                CapabilityReason::BackendUnavailable { backends: missing }
1036            }
1037            _ => CapabilityReason::NoRoute,
1038        }
1039    }
1040
1041    /// Enumerate policy-filtered routes between two formats.
1042    ///
1043    /// Uses the supplied policy, not necessarily [`Self::policy`]. Does not inspect
1044    /// files or filter by backend availability. See [`Graph::routes`] for ordering,
1045    /// bounded search, and partial-result behavior.
1046    ///
1047    /// # Examples
1048    ///
1049    /// ```rust
1050    /// use convert_rs::{ConversionKind, Converter, Policy};
1051    /// let converter = Converter::new();
1052    /// let plans = converter.plan("txt", "bin", converter.policy())?;
1053    /// assert_eq!(plans[0].steps[0].kind, ConversionKind::Lossless);
1054    /// assert!(converter.plan("bin", "txt", converter.policy()).is_err());
1055    /// let policy = Policy { allow_reinterpret: true, ..Policy::default() };
1056    /// let plans = converter.plan("bin", "txt", &policy)?;
1057    /// assert_eq!(plans[0].steps[0].operation, "decode-text");
1058    /// # Ok::<(), convert_rs::Error>(())
1059    /// ```
1060    ///
1061    /// # Errors
1062    ///
1063    /// Returns [`Error::Plan`] for unknown formats, invalid search settings, no
1064    /// route, or an exhausted search budget before any route is found.
1065    pub fn plan(&self, from: &str, to: &str, policy: &Policy) -> Result<Vec<Plan>> {
1066        Ok(self.graph.routes(from, to, policy)?)
1067    }
1068
1069    /// Convert files through the first successful route in the planned set.
1070    ///
1071    /// All inputs must resolve to one format. Routes are attempted in cost
1072    /// order, and every attempt re-stages fresh copies of inputs that adapters
1073    /// must not mutate. Search is bounded, so not every graph route is attempted.
1074    /// Backend filtering occurs after this bounded search. A forced plan bypasses
1075    /// search and is attempted once; see [`ConversionOptions::forced_plan`].
1076    ///
1077    /// With normal planning, same-format requests produce staged copies with an
1078    /// empty plan and no warnings. They do not validate content, re-encode, or
1079    /// choose codecs. File extensions and overrides are declarations, not decoder validation.
1080    /// Successful outputs remain temporary until copied out of the report.
1081    ///
1082    /// # Execute a reviewed plan
1083    ///
1084    /// ```rust
1085    /// use convert_rs::{ConversionKind, ConversionOptions, Converter, Policy};
1086    /// # #[tokio::main(flavor = "current_thread")]
1087    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
1088    /// let policy = Policy { allow_reinterpret: true, ..Policy::default() };
1089    /// let converter = Converter::new().with_policy(policy);
1090    /// let plans = converter.plan("bin", "txt", converter.policy())?;
1091    /// let chosen = plans.into_iter().next().ok_or("no plan")?;
1092    /// assert_eq!(chosen.steps[0].kind, ConversionKind::Reinterpret);
1093    /// let options = ConversionOptions {
1094    ///     from: Some("bin".into()),
1095    ///     backend: Some("builtin".into()),
1096    ///     forced_plan: Some(chosen),
1097    ///     ..ConversionOptions::default()
1098    /// };
1099    /// let inputs = tempfile::tempdir()?;
1100    /// let source = inputs.path().join("payload");
1101    /// std::fs::write(&source, "valid UTF-8")?;
1102    /// let report = converter.convert(&[source], "txt", &options).await?;
1103    /// assert_eq!(std::fs::read_to_string(&report.artifacts[0].path)?, "valid UTF-8");
1104    /// assert_eq!(report.warnings[0].kind, ConversionKind::Reinterpret);
1105    /// # Ok(())
1106    /// # }
1107    /// ```
1108    ///
1109    /// # Errors
1110    ///
1111    /// Returns [`Error::Invalid`] for empty input lists, unknown overrides or
1112    /// targets, mixed identified formats, or no route remaining after backend
1113    /// filtering; [`Error::Limit`] for too many inputs; and identification or
1114    /// planning errors before execution. Staging, adapter, execution-policy,
1115    /// and output-validation failures are accumulated into [`Error::RoutesFailed`]
1116    /// if all attempted routes fail. A successful fallback omits earlier errors.
1117    pub async fn convert(
1118        &self,
1119        paths: &[PathBuf],
1120        to: &str,
1121        options: &ConversionOptions,
1122    ) -> Result<ConversionReport> {
1123        options.validate()?;
1124        if paths.is_empty() {
1125            return Err(Error::Invalid("no input files given".into()));
1126        }
1127        if paths.len() > self.limits.max_artifacts {
1128            return Err(Error::Limit("input file count".into()));
1129        }
1130        let target = self
1131            .graph
1132            .resolve(to)
1133            .ok_or_else(|| Error::Invalid(format!("unknown target format: {to}")))?
1134            .id
1135            .clone();
1136
1137        let identification = match &options.from {
1138            Some(value) => {
1139                let format = self
1140                    .graph
1141                    .resolve(value)
1142                    .ok_or_else(|| Error::Invalid(format!("unknown source format: {value}")))?
1143                    .id
1144                    .clone();
1145                Identification {
1146                    format,
1147                    method: IdentificationMethod::Override,
1148                }
1149            }
1150            None => self.identify(&paths[0])?,
1151        };
1152        if options.from.is_none() {
1153            for path in &paths[1..] {
1154                let other = self.identify(path)?;
1155                if other.format != identification.format {
1156                    return Err(Error::Invalid(format!(
1157                        "inputs have different formats: {} and {}",
1158                        identification.format, other.format
1159                    )));
1160                }
1161            }
1162        }
1163        let source = identification.format;
1164
1165        let inspect = options.inspect_content || self.policy.inspect_content;
1166        let profile = if inspect && options.from.is_none() && options.forced_plan.is_none() {
1167            self.inspect(&paths[0], &source).await.0
1168        } else {
1169            None
1170        };
1171
1172        let plans = match &options.forced_plan {
1173            Some(plan) => vec![plan.clone()],
1174            None => {
1175                if source == target && options.reencode {
1176                    let reencode_policy = Policy {
1177                        reencode_same_format: true,
1178                        backends: options.backend.iter().cloned().collect(),
1179                        retain: normalized_retain(&options.preserve),
1180                        ..self.policy.clone()
1181                    };
1182                    match self.graph.routes_with_profile(
1183                        &source,
1184                        &target,
1185                        &reencode_policy,
1186                        profile.as_ref(),
1187                    ) {
1188                        Ok(plans) => plans,
1189                        Err(convert_rs_core::PlanError::NoRoute { .. }) => {
1190                            return Err(Error::Invalid(format!(
1191                                "no same-format re-encode route exists for {source}; \
1192                                 the copy path would ignore the reencode request"
1193                            )));
1194                        }
1195                        Err(error) => return Err(error.into()),
1196                    }
1197                } else {
1198                    let mut policy = self.policy.clone();
1199                    if let Some(backend) = &options.backend {
1200                        policy.backends = vec![backend.clone()];
1201                    }
1202                    if !options.preserve.is_empty() {
1203                        policy.retain = normalized_retain(&options.preserve);
1204                    }
1205                    let search =
1206                        self.graph
1207                            .routes_with_profile(&source, &target, &policy, profile.as_ref());
1208                    match (search, options.backend.as_ref()) {
1209                        (Ok(plans), _) => plans,
1210                        (Err(convert_rs_core::PlanError::NoRoute { .. }), Some(backend)) => {
1211                            return Err(Error::Invalid(format!(
1212                                "no route from {source} to {target} uses only backend {backend}"
1213                            )));
1214                        }
1215                        (Err(error), _) => return Err(error.into()),
1216                    }
1217                }
1218            }
1219        };
1220
1221        let mut attempts: Vec<RouteAttempt> = Vec::new();
1222        let mut failures = Vec::new();
1223        let target_format = self.graph.format(&target);
1224        for plan in plans {
1225            let forced = options.forced_plan.as_ref().is_some();
1226            let rejected = options
1227                .check_forced_retention(&plan)
1228                .and_then(|()| {
1229                    if forced {
1230                        match target_format {
1231                            Some(format) => options.check_forced_content(
1232                                &plan,
1233                                format,
1234                                profile.as_ref(),
1235                                &self.policy.require,
1236                                self.policy.require_content,
1237                            ),
1238                            None => Ok(()),
1239                        }
1240                    } else {
1241                        Ok(())
1242                    }
1243                })
1244                .err();
1245            if let Some(error) = rejected {
1246                let index = attempts.len();
1247                attempts.push(RouteAttempt::new(
1248                    index,
1249                    render_route(&plan),
1250                    plan.clone(),
1251                    Some(error.to_string()),
1252                ));
1253                failures.push(format!("{}: {error}", attempts[index].route));
1254                continue;
1255            }
1256            let index = attempts.len();
1257            let rendered = render_route(&plan);
1258            let attempt = self.execute(&plan, &source, &target, paths, options).await;
1259            match attempt {
1260                Ok(mut report) => {
1261                    let accepted = RouteAttempt::new(index, rendered, plan.clone(), None);
1262                    report.attempts = attempts;
1263                    report.attempts.push(accepted);
1264                    return Ok(report);
1265                }
1266                Err(error) => {
1267                    attempts.push(RouteAttempt::new(
1268                        index,
1269                        rendered,
1270                        plan.clone(),
1271                        Some(error.to_string()),
1272                    ));
1273                    failures.push(format!("{}: {error}", attempts[index].route));
1274                }
1275            }
1276        }
1277        Err(Error::RoutesFailed(failures.join("; ")))
1278    }
1279
1280    /// Convert one in-memory buffer, returning its converted bytes.
1281    ///
1282    /// Writes the input to a staged temporary file, runs
1283    /// [`Self::convert`] with these options, verifies that exactly one
1284    /// artifact was produced, and reads it back. The report is dropped
1285    /// afterwards, so nothing to clean up. Requires a Tokio runtime; use
1286    /// [`Self::convert_blocking`] from synchronous code.
1287    ///
1288    /// # Errors
1289    ///
1290    /// Identifies the buffer by content (extension-based lookup cannot apply);
1291    /// returns [`Error::Conversion`] when a multi-output route (for example
1292    /// archive extraction) is selected, plus any error from [`Self::convert`].
1293    pub async fn convert_bytes(
1294        &self,
1295        input: &[u8],
1296        from: &str,
1297        to: &str,
1298        options: &ConversionOptions,
1299    ) -> Result<Vec<u8>> {
1300        let source_format = self
1301            .graph
1302            .resolve(from)
1303            .ok_or_else(|| Error::Invalid(format!("unknown source format: {from}")))?
1304            .id
1305            .clone();
1306        let workspace = TempDir::new()?;
1307        let staged_path = workspace.path().join("input");
1308        std::fs::write(&staged_path, input)?;
1309        let options = ConversionOptions {
1310            from: Some(source_format),
1311            ..options.clone()
1312        };
1313        let report = self
1314            .convert(std::slice::from_ref(&staged_path), to, &options)
1315            .await?;
1316        let [artifact] = report.artifacts.as_slice() else {
1317            return Err(Error::Conversion(format!(
1318                "route produced {} artifacts; convert_bytes needs exactly one",
1319                report.artifacts.len()
1320            )));
1321        };
1322        Ok(std::fs::read(&artifact.path)?)
1323    }
1324
1325    /// Synchronous [`Self::convert_bytes`] for callers without a Tokio runtime.
1326    ///
1327    /// Builds a single-threaded runtime internally and blocks the current
1328    /// thread; calling it from an existing async context deadlocks.
1329    ///
1330    /// # Errors
1331    ///
1332    /// As [`Self::convert`], plus [`Error::Invalid`] if the runtime cannot be
1333    /// constructed (for example nested inside another Tokio runtime).
1334    pub fn convert_blocking(
1335        &self,
1336        input: &[u8],
1337        from: &str,
1338        to: &str,
1339        options: &ConversionOptions,
1340    ) -> Result<Vec<u8>> {
1341        let runtime = tokio::runtime::Builder::new_current_thread()
1342            .enable_all()
1343            .build()
1344            .map_err(|error| Error::Invalid(format!("cannot build a blocking runtime: {error}")))?;
1345        runtime.block_on(self.convert_bytes(input, from, to, options))
1346    }
1347
1348    async fn execute(
1349        &self,
1350        plan: &Plan,
1351        source: &str,
1352        target: &str,
1353        paths: &[PathBuf],
1354        options: &ConversionOptions,
1355    ) -> Result<ConversionReport> {
1356        let pinned = &options.backend;
1357        let workspace = TempDir::new()?;
1358        let mut artifacts = Vec::with_capacity(paths.len());
1359        for (index, path) in paths.iter().enumerate() {
1360            artifacts.push(stage_input(
1361                path,
1362                workspace.path(),
1363                index,
1364                source,
1365                &self.limits,
1366            )?);
1367        }
1368
1369        let mut warnings = Vec::new();
1370        let mut costs = Vec::new();
1371        let mut spent_total = 0u64;
1372        for (index, step) in plan.steps.iter().enumerate() {
1373            if !self.policy.allows(step.kind) {
1374                return Err(Error::Security(format!(
1375                    "{:?} steps are disabled",
1376                    step.kind
1377                )));
1378            }
1379            if step.external && !self.policy.allow_external {
1380                return Err(Error::Security(format!(
1381                    "{} uses a native external tool; enable Policy::allow_external",
1382                    step.backend
1383                )));
1384            }
1385            if pinned
1386                .as_ref()
1387                .is_some_and(|backend| &step.backend != backend)
1388            {
1389                return Err(Error::Invalid("plan uses a disallowed backend".into()));
1390            }
1391            if artifacts
1392                .iter()
1393                .any(|artifact| artifact.format != step.from)
1394            {
1395                return Err(Error::Conversion(format!(
1396                    "step {index} expected {} inputs",
1397                    step.from
1398                )));
1399            }
1400            let adapter = self.adapters.get(&step.backend).ok_or_else(|| {
1401                Error::Conversion(format!("backend {} is not registered", step.backend))
1402            })?;
1403            let step_dir = workspace.path().join(step_dir_name(index)?);
1404            tokio::fs::create_dir_all(&step_dir).await?;
1405            let request = StepRequest::new(
1406                artifacts.clone(),
1407                step_dir.clone(),
1408                step.from.clone(),
1409                step.to.clone(),
1410                step.operation.clone(),
1411                self.limits.clone(),
1412            )
1413            .with_params(&options.params)
1414            .with_spent_output_bytes(spent_total);
1415            match adapter.convert(&request).await {
1416                Ok(produced) => {
1417                    let (validated, produced_bytes) = validate_artifacts(
1418                        produced,
1419                        &step_dir,
1420                        step,
1421                        &self.limits,
1422                        &self.graph,
1423                        options,
1424                        &self.adapters,
1425                    )?;
1426                    artifacts = validated;
1427                    spent_total = spent_total.saturating_add(produced_bytes);
1428                    if self.limits.max_total_output_bytes > 0
1429                        && spent_total > self.limits.max_total_output_bytes
1430                    {
1431                        return Err(Error::Limit(
1432                            "combined step outputs exceed the total byte budget".into(),
1433                        ));
1434                    }
1435                }
1436                Err(error) => {
1437                    let _ = tokio::fs::remove_dir_all(&step_dir).await;
1438                    return Err(error);
1439                }
1440            }
1441            if let Some(warning) = warning_for(index, step) {
1442                warnings.push(warning);
1443            }
1444            if step.kind != ConversionKind::Lossless {
1445                costs.push(StepCost::new(
1446                    index,
1447                    &step.backend,
1448                    &step.operation,
1449                    step.kind,
1450                    step.cost,
1451                    step.note.as_deref(),
1452                ));
1453            }
1454        }
1455        if artifacts.iter().any(|artifact| artifact.format != *target) {
1456            return Err(Error::Conversion(
1457                "final artifacts do not match the target".into(),
1458            ));
1459        }
1460        if options.verify && plan.steps.is_empty() {
1461            let identity = crate::Conversion::new(
1462                source,
1463                target,
1464                "engine",
1465                "identity",
1466                crate::ConversionKind::Lossless,
1467                0,
1468            );
1469            for artifact in &artifacts {
1470                verify_artifact_bytes(
1471                    &artifact.path,
1472                    &identity,
1473                    &self.graph,
1474                    &self.adapters,
1475                    &self.limits,
1476                )?;
1477            }
1478        }
1479        let ignored_params = ignored_param_keys(plan, options, &self.adapters);
1480        Ok(ConversionReport {
1481            workspace,
1482            plan: plan.clone(),
1483            artifacts,
1484            warnings,
1485            costs,
1486            attempts: Vec::new(),
1487            ignored_params,
1488        })
1489    }
1490}
1491
1492/// Requested param keys that no executed step's adapter declared support for.
1493fn ignored_param_keys(
1494    plan: &Plan,
1495    options: &ConversionOptions,
1496    adapters: &BTreeMap<String, Arc<dyn crate::Adapter>>,
1497) -> Vec<String> {
1498    if options.params.is_empty() {
1499        return Vec::new();
1500    }
1501    let mut supported: std::collections::BTreeSet<String> = std::collections::BTreeSet::new();
1502    for step in &plan.steps {
1503        if let Some(adapter) = adapters.get(&step.backend) {
1504            supported.extend(
1505                adapter
1506                    .param_keys(&step.operation)
1507                    .iter()
1508                    .map(|key| key.trim().to_ascii_lowercase()),
1509            );
1510        }
1511    }
1512    options
1513        .params
1514        .keys()
1515        .filter(|key| !supported.contains(&key.trim().to_ascii_lowercase()))
1516        .cloned()
1517        .collect()
1518}
1519
1520fn step_dir_name(index: usize) -> Result<String> {
1521    Ok(format!("step-{index:04}"))
1522}
1523
1524/// Lowercase and trim requested retention property names, dropping blanks.
1525fn normalized_retain(values: &[String]) -> Vec<String> {
1526    let mut normalized: Vec<String> = values
1527        .iter()
1528        .map(|value| value.trim().to_ascii_lowercase())
1529        .filter(|value| !value.is_empty())
1530        .collect();
1531    normalized.sort();
1532    normalized.dedup();
1533    normalized
1534}
1535
1536/// Render a plan's route as a single line, e.g. `identity` or `a→b via x | b→c via y`.
1537fn render_route(plan: &Plan) -> String {
1538    if plan.steps.is_empty() {
1539        "identity".to_owned()
1540    } else {
1541        plan.steps
1542            .iter()
1543            .map(|step| format!("{}→{} via {}", step.from, step.to, step.backend))
1544            .collect::<Vec<_>>()
1545            .join(" | ")
1546    }
1547}
1548
1549fn warning_for(index: usize, step: &crate::Conversion) -> Option<Warning> {
1550    let generic = match step.kind {
1551        ConversionKind::Lossless => return None,
1552        ConversionKind::Lossy => format!(
1553            "{} re-encoded through {}; expect quality or metadata loss",
1554            step.to, step.operation
1555        ),
1556        ConversionKind::Reencode => format!(
1557            "{} re-encoded in place through {}; expect quality or metadata loss",
1558            step.to, step.operation
1559        ),
1560        ConversionKind::Bridge => format!(
1561            "{} bridged through {}; the result expresses {} differently",
1562            step.from, step.operation, step.to
1563        ),
1564        ConversionKind::Reinterpret => format!(
1565            "bytes were reinterpreted as {} by {}",
1566            step.to, step.backend
1567        ),
1568        ConversionKind::Package => "files were packaged; contents were not converted".into(),
1569        ConversionKind::Extract => "archive members were extracted as separate files".into(),
1570    };
1571    let message = match &step.note {
1572        Some(note) => format!("{generic}: {note}"),
1573        None => generic,
1574    };
1575    Some(Warning {
1576        step: index,
1577        backend: step.backend.clone(),
1578        operation: step.operation.clone(),
1579        kind: step.kind,
1580        message,
1581    })
1582}
1583
1584/// Candidate suffix lookups for a file name, longest first.
1585///
1586/// `archive.tar.gz` yields `["tar.gz", "gz"]`; `note.txt` yields `["txt"]`.
1587/// Each candidate is matched only when a registered extension equals it, so
1588/// unknown suffixes fall through to signature detection.
1589fn extensions_of(path: &Path) -> Vec<String> {
1590    let Some(name) = path.file_name().and_then(|name| name.to_str()) else {
1591        return Vec::new();
1592    };
1593    let Some(dotted) = name.split_once('.').map(|(_, rest)| rest) else {
1594        return Vec::new();
1595    };
1596    let mut candidates = Vec::new();
1597    let mut rest = dotted;
1598    while let Some(index) = rest.rfind('.') {
1599        candidates.push(rest.to_ascii_lowercase());
1600        rest = &rest[index + 1..];
1601    }
1602    if !rest.is_empty() {
1603        candidates.push(rest.to_ascii_lowercase());
1604    }
1605    candidates
1606}
1607
1608fn stage_input(
1609    path: &Path,
1610    dir: &Path,
1611    index: usize,
1612    format: &str,
1613    limits: &Limits,
1614) -> Result<Artifact> {
1615    let metadata = std::fs::symlink_metadata(path)?;
1616    if !metadata.file_type().is_file() {
1617        return Err(Error::Security("input is not a regular file".into()));
1618    }
1619    if metadata.len() > limits.max_input_bytes {
1620        return Err(Error::Limit("input bytes exceed budget".into()));
1621    }
1622    let destination = dir.join(format!("input-{index}"));
1623    std::fs::copy(path, &destination)?;
1624    let staged = std::fs::symlink_metadata(&destination)?;
1625    if !staged.file_type().is_file() || staged.len() != metadata.len() {
1626        return Err(Error::Security("staged input changed during copy".into()));
1627    }
1628    Ok(Artifact::new(destination, format.to_owned()))
1629}
1630
1631/// Ensure an adapter produced only bounded regular files inside its own step
1632/// directory and that no intermediate directory contains path-traversal names.
1633///
1634/// Returns the validated artifacts and their total byte count so the caller can
1635/// track the cumulative [`Limits::max_total_output_bytes`] budget.
1636fn validate_artifacts(
1637    produced: Vec<Artifact>,
1638    step_dir: &Path,
1639    step: &crate::Conversion,
1640    limits: &Limits,
1641    graph: &Graph,
1642    options: &ConversionOptions,
1643    adapters: &BTreeMap<String, Arc<dyn Adapter>>,
1644) -> Result<(Vec<Artifact>, u64)> {
1645    if produced.len() > limits.max_artifacts {
1646        return Err(Error::Limit("adapter produced too many artifacts".into()));
1647    }
1648    let root = step_dir
1649        .canonicalize()
1650        .map_err(|_| Error::Security("step directory disappeared".into()))?;
1651    let mut artifacts = Vec::with_capacity(produced.len());
1652    let mut total = 0u64;
1653    for artifact in produced {
1654        if artifact.format != step.to {
1655            return Err(Error::Conversion(format!(
1656                "{} returned a {} artifact for a {} step",
1657                step.backend, artifact.format, step.to
1658            )));
1659        }
1660        let metadata = std::fs::symlink_metadata(&artifact.path)
1661            .map_err(|_| Error::Security("adapter artifact does not exist".into()))?;
1662        if !metadata.file_type().is_file() {
1663            return Err(Error::Security(
1664                "adapter returned a non-regular file".into(),
1665            ));
1666        }
1667        let canonical = artifact.path.canonicalize().map_err(|_| {
1668            Error::Security("adapter returned a path that cannot be resolved".into())
1669        })?;
1670        if !canonical.starts_with(&root) {
1671            return Err(Error::Security(
1672                "adapter wrote outside its step directory".into(),
1673            ));
1674        }
1675        if options.verify {
1676            verify_artifact_bytes(&canonical, step, graph, adapters, limits)?;
1677        }
1678        total = total
1679            .checked_add(metadata.len())
1680            .ok_or_else(|| Error::Limit("artifact byte overflow".into()))?;
1681        if total > limits.max_output_bytes {
1682            return Err(Error::Limit("artifact bytes exceed budget".into()));
1683        }
1684        let mut validated = Artifact::new(canonical, artifact.format);
1685        validated.logical_name = artifact.logical_name;
1686        artifacts.push(validated);
1687    }
1688    Ok((artifacts, total))
1689}
1690
1691/// Re-sniff an artifact's first bytes and ask available decoders to confirm them.
1692///
1693/// Detection covers registered magic signatures; when no signature matches the
1694/// content, verification defers to the adapters. A signature that resolves to
1695/// a different registered format is a contradiction and fails the route. After
1696/// the signature check passes, available adapters that can judge the declared
1697/// format through [`crate::Adapter::accepts_input`] get a say: `Some(false)`
1698/// rejects the artifact, and `None` (the default) expresses no opinion.
1699fn verify_artifact_bytes(
1700    path: &Path,
1701    step: &crate::Conversion,
1702    graph: &Graph,
1703    adapters: &BTreeMap<String, Arc<dyn Adapter>>,
1704    limits: &Limits,
1705) -> Result<()> {
1706    // bin holds arbitrary bytes and identity relabels are caller assertions;
1707    // a signature hit on either target is expected, not a contradiction.
1708    if step.to != "bin"
1709        && step.from != step.to
1710        && let Some(contradiction) = sniff_contradiction(path, step, graph)?
1711    {
1712        return Err(contradiction);
1713    }
1714    for adapter in adapters.values() {
1715        if adapter.name() == step.backend || !adapter.status().available {
1716            continue;
1717        }
1718        if adapter.accepts_input(path, &step.to, limits) == Some(false) {
1719            return Err(Error::Conversion(format!(
1720                "verification failed: {} cannot decode what {} wrote as {}",
1721                adapter.name(),
1722                step.backend,
1723                step.to
1724            )));
1725        }
1726    }
1727    Ok(())
1728}
1729
1730/// Return the error describing a signature contradiction, or `None` when the
1731/// bytes agree with (or say nothing about) the declared target format.
1732fn sniff_contradiction(
1733    path: &Path,
1734    step: &crate::Conversion,
1735    graph: &Graph,
1736) -> Result<Option<Error>> {
1737    let mut header = [0u8; 1024];
1738    let mut file = std::fs::File::open(path)
1739        .map_err(|_| Error::Security("artifact became unreadable during verification".into()))?;
1740    let count = file.read(&mut header).map_err(|_| {
1741        Error::Security(format!(
1742            "artifact {} cannot be re-read for verification",
1743            path.display()
1744        ))
1745    })?;
1746    if count == 0 {
1747        return Ok(None);
1748    }
1749    let Some(name) = detect(&header[..count]) else {
1750        return Ok(None);
1751    };
1752    let Some(resolved) = graph.resolve(name) else {
1753        return Ok(None);
1754    };
1755    // A compound container is allowed to sniff as its inner format: a valid
1756    // `tar.gz` file begins with the gzip signature, so `tar.gz` accepts a `gz`
1757    // detection. Anything else that contradicts the declared format fails.
1758    if resolved.id == step.to || step.to.ends_with(&format!(".{}", resolved.id)) {
1759        return Ok(None);
1760    }
1761    Ok(Some(Error::Conversion(format!(
1762        "verification failed: {} wrote a {} file while the step claims {}",
1763        step.backend, resolved.id, step.to
1764    ))))
1765}
1766
1767#[cfg(test)]
1768#[allow(clippy::unwrap_used, clippy::expect_used)]
1769mod tests {
1770    use super::*;
1771
1772    fn graph_backend_converter() -> Converter {
1773        Converter::new()
1774    }
1775
1776    #[test]
1777    fn registration_is_idempotent_by_name() {
1778        let converter = graph_backend_converter();
1779        assert_eq!(
1780            converter
1781                .order
1782                .iter()
1783                .filter(|name| name.as_str() == "builtin")
1784                .count(),
1785            1
1786        );
1787    }
1788
1789    #[test]
1790    #[cfg(feature = "media")]
1791    fn extension_detection_wins_and_magic_is_fallback() {
1792        let converter = graph_backend_converter();
1793        let dir = TempDir::new().unwrap();
1794        std::fs::write(dir.path().join("note.txt"), b"plain text").unwrap();
1795        assert_eq!(
1796            converter
1797                .identify(&dir.path().join("note.txt"))
1798                .unwrap()
1799                .method,
1800            IdentificationMethod::Extension
1801        );
1802        std::fs::write(dir.path().join("payload.dat"), b"\x89PNG\r\n\x1a\nxx").unwrap();
1803        let found = converter.identify(&dir.path().join("payload.dat")).unwrap();
1804        assert_eq!(found.format, "png");
1805        assert_eq!(found.method, IdentificationMethod::Magic);
1806        std::fs::write(dir.path().join("random"), [1, 2, 3, 250, 7]).unwrap();
1807        let found = converter.identify(&dir.path().join("random")).unwrap();
1808        assert_eq!(found.format, "bin");
1809        assert_eq!(found.method, IdentificationMethod::Unknown);
1810    }
1811
1812    #[test]
1813    fn identify_rejects_nonregular_and_empty() {
1814        let converter = graph_backend_converter();
1815        let dir = TempDir::new().unwrap();
1816        std::fs::create_dir(dir.path().join("adir")).unwrap();
1817        assert!(matches!(
1818            converter.identify(&dir.path().join("adir")),
1819            Err(Error::Security(_))
1820        ));
1821        std::fs::write(dir.path().join("empty.txt"), b"").unwrap();
1822        assert!(matches!(
1823            converter.identify(&dir.path().join("empty.txt")),
1824            Err(Error::Security(_))
1825        ));
1826    }
1827
1828    #[tokio::test]
1829    async fn unknown_files_require_reinterpretation_opt_in() {
1830        let converter = graph_backend_converter();
1831        let dir = TempDir::new().unwrap();
1832        let path = dir.path().join("mystery");
1833        std::fs::write(&path, [7u8; 40]).unwrap();
1834        let default = converter
1835            .convert(
1836                std::slice::from_ref(&path),
1837                "txt",
1838                &ConversionOptions::default(),
1839            )
1840            .await;
1841        assert!(matches!(default, Err(Error::Plan(_))), "{default:?}");
1842        let policy = Policy {
1843            allow_reinterpret: true,
1844            ..Policy::default()
1845        };
1846        let report = Converter::default()
1847            .with_policy(policy)
1848            .convert(&[path], "txt", &ConversionOptions::default())
1849            .await
1850            .unwrap();
1851        assert_eq!(report.plan.steps.len(), 1);
1852        assert!(
1853            report
1854                .warnings
1855                .iter()
1856                .any(|warning| warning.kind == ConversionKind::Reinterpret)
1857        );
1858    }
1859
1860    #[tokio::test]
1861    async fn same_format_requests_stage_a_copy() {
1862        let converter = graph_backend_converter();
1863        let dir = TempDir::new().unwrap();
1864        let path = dir.path().join("data.txt");
1865        std::fs::write(&path, b"unchanged").unwrap();
1866        let report = converter
1867            .convert(&[path], "txt", &ConversionOptions::default())
1868            .await
1869            .unwrap();
1870        assert!(report.plan.steps.is_empty());
1871        assert_eq!(
1872            std::fs::read_to_string(&report.artifacts[0].path).unwrap(),
1873            "unchanged"
1874        );
1875    }
1876
1877    #[tokio::test]
1878    async fn mixed_format_inputs_are_rejected() {
1879        let converter = graph_backend_converter();
1880        let dir = TempDir::new().unwrap();
1881        std::fs::write(dir.path().join("a.txt"), b"a").unwrap();
1882        std::fs::write(dir.path().join("b.gz"), b"\x1f\x8brest").unwrap();
1883        let error = converter
1884            .convert(
1885                &[dir.path().join("a.txt"), dir.path().join("b.gz")],
1886                "tar",
1887                &ConversionOptions::default(),
1888            )
1889            .await
1890            .err();
1891        assert!(matches!(error, Some(Error::Invalid(_))));
1892    }
1893
1894    #[test]
1895    fn validating_artifacts_rejects_escapes_and_mismatch() {
1896        let dir = TempDir::new().unwrap();
1897        let step_dir = dir.path().join("step");
1898        std::fs::create_dir(&step_dir).unwrap();
1899        let step = crate::Conversion::new(
1900            "a",
1901            "png",
1902            "backend",
1903            "convert",
1904            ConversionKind::Lossless,
1905            1,
1906        );
1907        let limits = Limits::default();
1908
1909        let graph = Graph::new();
1910        let defaults = ConversionOptions::default();
1911        std::fs::write(dir.path().join("escape.png"), b"x").unwrap();
1912        let escape = Artifact::new(dir.path().join("escape.png"), "png");
1913        assert!(matches!(
1914            validate_artifacts(
1915                vec![escape],
1916                &step_dir,
1917                &step,
1918                &limits,
1919                &graph,
1920                &defaults,
1921                &BTreeMap::new()
1922            ),
1923            Err(Error::Security(_))
1924        ));
1925
1926        let directory = Artifact::new(step_dir.clone(), "png");
1927        assert!(matches!(
1928            validate_artifacts(
1929                vec![directory],
1930                &step_dir,
1931                &step,
1932                &limits,
1933                &graph,
1934                &defaults,
1935                &BTreeMap::new(),
1936            ),
1937            Err(Error::Security(_))
1938        ));
1939
1940        let wrong = Artifact::new(step_dir.join("wrong.jpg"), "jpeg".to_owned());
1941        std::fs::write(&wrong.path, b"x").unwrap();
1942        assert!(matches!(
1943            validate_artifacts(
1944                vec![wrong],
1945                &step_dir,
1946                &step,
1947                &limits,
1948                &graph,
1949                &defaults,
1950                &BTreeMap::new()
1951            ),
1952            Err(Error::Conversion(_))
1953        ));
1954
1955        std::fs::write(step_dir.join("real.png"), b"x").unwrap();
1956        let good = Artifact::new(step_dir.join("real.png"), "png");
1957        assert_eq!(
1958            validate_artifacts(
1959                vec![good],
1960                &step_dir,
1961                &step,
1962                &limits,
1963                &graph,
1964                &defaults,
1965                &BTreeMap::new()
1966            )
1967            .unwrap()
1968            .0
1969            .len(),
1970            1
1971        );
1972    }
1973
1974    #[test]
1975    fn stage_input_rejects_nonregular_and_oversize() {
1976        let limits = Limits {
1977            max_input_bytes: 4,
1978            ..Limits::default()
1979        };
1980        let dir = TempDir::new().unwrap();
1981        let path = dir.path().join("in");
1982        std::fs::write(&path, b"payload").unwrap();
1983        assert!(matches!(
1984            stage_input(&path, dir.path(), 0, "bin", &limits),
1985            Err(Error::Limit(_))
1986        ));
1987        std::fs::create_dir(dir.path().join("adir")).unwrap();
1988        assert!(matches!(
1989            stage_input(
1990                &dir.path().join("adir"),
1991                dir.path(),
1992                1,
1993                "bin",
1994                &Limits::default()
1995            ),
1996            Err(Error::Security(_))
1997        ));
1998    }
1999
2000    #[tokio::test]
2001    async fn backend_constraint_selects_or_rejects_routes() {
2002        let converter = graph_backend_converter();
2003        let dir = TempDir::new().unwrap();
2004        std::fs::write(dir.path().join("data.txt"), b"[1, 2, 3]").unwrap();
2005        let options = ConversionOptions {
2006            from: Some("txt".into()),
2007            backend: Some("builtin".into()),
2008            ..ConversionOptions::default()
2009        };
2010        let report = converter
2011            .convert(&[dir.path().join("data.txt")], "csv", &options)
2012            .await
2013            .err();
2014        assert!(report.is_some(),);
2015    }
2016
2017    #[test]
2018    #[cfg(feature = "media")]
2019    fn graph_routes_honor_policy() {
2020        let converter = graph_backend_converter();
2021        let strict = converter
2022            .plan("bin", "png", &Policy::default())
2023            .unwrap_err();
2024        assert!(matches!(
2025            strict,
2026            Error::Plan(convert_rs_core::PlanError::NoRoute { .. })
2027        ));
2028    }
2029}