{
  "generator": {
    "matra": "0.3.0",
    "udpipe_model": {
      "name": "english-ewt-ud-2.5-191206",
      "sha256": "784bd0fa85e3d831fd02a55290d0acfd05c953159dc38cc33d52e1b28add9957"
    }
  },
  "page": "reference/errors.md",
  "paragraphs": [
    {
      "compression_ratio": 0.5861,
      "kind": "paragraph",
      "lexical_density": 0.6444,
      "readability_grade": 13.5978,
      "sentences": 3,
      "text": "Every fallible function in matra returns domain::Result<T>, which is std::result::Result<T, domain::Error>. No function in the library returns Result<T, String>. matra signals failure by returning Error, not by unwinding: a panic raised inside the UDPipe C++ boundary is caught at the adapter and converted into Error::ParseFailed.",
      "words": 56
    },
    {
      "compression_ratio": 0.6422,
      "kind": "paragraph",
      "lexical_density": 0.5179,
      "readability_grade": 6.9379,
      "sentences": 4,
      "text": "Error is #[non_exhaustive]. Variants can be added in a minor release, so a match on it from another crate needs a catch-all arm. Error does not derive Clone; it is moved, not copied. The stream surface wraps it in DocumentError, which adds the path the failure occurred at, and yields it as that input's Err item.",
      "words": 59
    },
    {
      "compression_ratio": 0.4965,
      "kind": "paragraph",
      "lexical_density": 0.5,
      "readability_grade": 6.8396,
      "sentences": 8,
      "text": "Every error reads the same way on every channel. It has a kind, a stable string to branch on. It has a message, for a person. And it has details: the values a caller acts on, as named data, so nothing has to parse the message. For every kind but invalid_input that is every dynamic value in the message; an invalid_input names the check that failed, and its message adds the values that failed it for a person. In Rust these are Error::kind, Display and Error::details. The serde form is the three together, and Python exceptions carry the same three. See kinds and details.",
      "words": 106
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.6667,
      "readability_grade": 13.295,
      "sentences": 1,
      "text": "Error implements std::error::Error and Display through thiserror, and From<std::io::Error>, so ? converts I/O failures automatically.",
      "words": 20
    },
    {
      "compression_ratio": 0.625,
      "kind": "paragraph",
      "lexical_density": 0.5532,
      "readability_grade": 11.6094,
      "sentences": 3,
      "text": "Returned by Model2Vec::from_dir when any of the three artifacts is absent. The payload is the path of the first one missing. Neither the UDPipe provisioner, behind Engine::new and Engine::from_config in Rust and Python, nor Model2Vec::potion_base_8m returns this variant: both download the model when the file is absent.",
      "words": 51
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5,
      "readability_grade": null,
      "sentences": 1,
      "text": "Returned by:",
      "words": 2
    },
    {
      "compression_ratio": null,
      "kind": "list_item",
      "lexical_density": 0.5854,
      "readability_grade": 9.8863,
      "sentences": 3,
      "text": "The UDPipe provisioner when the bytes it downloaded still fail SHA-256 verification after one refetch. The payload is SHA-256 mismatch after re-download from <url>. Nothing that failed verification is written, so the model directory is left as the call found it.",
      "words": 44
    },
    {
      "compression_ratio": null,
      "kind": "list_item",
      "lexical_density": 0.5,
      "readability_grade": 11.0967,
      "sentences": 1,
      "text": "Model2Vec::from_dir when an artifact does not parse, uses an embedding dtype other than f32, or panics the loader.",
      "words": 18
    },
    {
      "compression_ratio": null,
      "kind": "list_item",
      "lexical_density": 0.4359,
      "readability_grade": 11.9842,
      "sentences": 2,
      "text": "Model2Vec::potion_base_8m when the directory already holds all three artifacts and their digest is not the pinned one, or holds only some of them. The payload names the directory and the ways out; nothing there is downloaded over or removed.",
      "words": 40
    },
    {
      "compression_ratio": null,
      "kind": "list_item",
      "lexical_density": 0.5714,
      "readability_grade": 11.7843,
      "sentences": 3,
      "text": "Model2Vec::potion_base_8m when the artifacts it downloaded still fail the digest after one re-download. Both attempts verify in memory, so neither writes anything, and the directory is left exactly as the call found it. The payload names the directory and the expected digest.",
      "words": 42
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5556,
      "readability_grade": 7.8189,
      "sentences": 1,
      "text": "A file whose hash does not match the pinned constant is treated as untrusted and is never loaded.",
      "words": 18
    },
    {
      "compression_ratio": 0.5707,
      "kind": "paragraph",
      "lexical_density": 0.5484,
      "readability_grade": 10.3718,
      "sentences": 3,
      "text": "ModelInvalid is about bytes that arrived. A download that never arrived, a server that answered about the request rather than with a model, and a filesystem that refused the write are Io, not ModelInvalid (RFC-0015). Before 0.2.0 the UDPipe download funnelled all three here, so a DNS failure reported model_invalid; a consumer that branched on that reads the provisioning failures section below.",
      "words": 63
    },
    {
      "compression_ratio": 0.5784,
      "kind": "paragraph",
      "lexical_density": 0.4444,
      "readability_grade": 7.6004,
      "sentences": 3,
      "text": "The parser or a reader failed on the input, or returned what its contract forbids. The remedy is the component, not the call: the same input through the same parser fails the same way. cause is free text for a person, and reason is present when the failure is one of the engine's checks.",
      "words": 55
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5238,
      "readability_grade": 10.019,
      "sentences": 2,
      "text": "A parser or a reader reports its own failure with reason None. The UDPipe adapter's parse does so in four situations:",
      "words": 22
    },
    {
      "compression_ratio": null,
      "kind": "list_item",
      "lexical_density": 0.5833,
      "readability_grade": 5.4333,
      "sentences": 2,
      "text": "The underlying parser returns an error. The cause is that error's message.",
      "words": 13
    },
    {
      "compression_ratio": null,
      "kind": "list_item",
      "lexical_density": 0.6486,
      "readability_grade": 9.3851,
      "sentences": 3,
      "text": "The underlying parser panics. The cause is udpipe panicked: <message>. The catch_unwind boundary that produces this lives in nlp/udpipe.rs, and it exists because an unhandled panic crossing the C++ boundary aborts the host process instead of unwinding.",
      "words": 40
    },
    {
      "compression_ratio": null,
      "kind": "list_item",
      "lexical_density": 0.5789,
      "readability_grade": 5.5045,
      "sentences": 2,
      "text": "A token id or head value cannot be represented as usize. The cause names the token and its sentence.",
      "words": 20
    },
    {
      "compression_ratio": 0.5637,
      "kind": "list_item",
      "lexical_density": 0.4898,
      "readability_grade": 7.1555,
      "sentences": 3,
      "text": "A token's form cannot be found in the paragraph text the parser was given, at or after the previous token, so the token has no span. The cause names the token, its sentence and the byte the search began at. The adapter reports this rather than a guessed span.",
      "words": 52
    },
    {
      "compression_ratio": 0.5127,
      "kind": "paragraph",
      "lexical_density": 0.5692,
      "readability_grade": 30.6369,
      "sentences": 2,
      "text": "The engine trusts no parser and no reader, matra's own included. Before anything a reader returns becomes a section, and before anything the parser returns for a paragraph becomes a sentence, the engine checks it against the contract its trait states (matra::decompose::Decomposer, matra::nlp::NlpProvider), and a break fails the document with reason naming the check and cause naming the block, or the paragraph, sentence and token:",
      "words": 68
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5455,
      "readability_grade": 7.5618,
      "sentences": 2,
      "text": "A conforming parser or reader is one whose output passes these checks on every input it accepts. The checks are a pass over what they read: on the docsite's own pages they cost about 0.014% of UDPipe's parse time, about 3 microseconds a paragraph.",
      "words": 48
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.6,
      "readability_grade": 5.42,
      "sentences": 2,
      "text": "Ten gate labels produce this variant. The what field carries the label so a caller can route each gate differently.",
      "words": 20
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5918,
      "readability_grade": 10.5269,
      "sentences": 3,
      "text": "limit carries the cap and actual carries the measured size, so an error message can be built without hardcoding the constants. Each cap is a published constant in domain::limits, named in the table; the module's documentation carries the cost model behind each value. No configuration changes any of them.",
      "words": 50
    },
    {
      "compression_ratio": 0.5212,
      "kind": "paragraph",
      "lexical_density": 0.5833,
      "readability_grade": 6.8465,
      "sentences": 5,
      "text": "The caps bound worst-case memory and time. TextRank builds a dense similarity matrix that reaches roughly 32 MB of f64 at 2,000 sentences. RAKE and YAKE build phrase-keyed maps whose size follows token count rather than sentence count, which is why their caps are stated in tokens. The two download caps are the gates whose input is not the caller's: they bound what a redirected or misbehaving server can make the process hold, and the read stops at the bound rather than continuing, so actual reports the bound that was breached rather than the response's full length. Both are 64 MiB per file, against the 16.3 MB parsing model and the embedding model's largest file, 30.2 MB of its 30.9 MB set, which is headroom for a later version and still finite.",
      "words": 137
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5238,
      "readability_grade": 9.1762,
      "sentences": 2,
      "text": "A document from disk crosses both gates in sequence: \"file_read\" when the file is read, \"input\" before it is parsed. In practice \"file_read\" fires first, since both carry the same 8 MiB limit and the file size is checked before the read.",
      "words": 42
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.4828,
      "readability_grade": 11.589,
      "sentences": 1,
      "text": "Every route from text to a parser, a parser of your own included, runs through the engine, so no text bypasses the \"input\" gate on its way to one.",
      "words": 29
    },
    {
      "compression_ratio": 0.5883,
      "kind": "paragraph",
      "lexical_density": 0.5222,
      "readability_grade": 9.3922,
      "sentences": 4,
      "text": "The label has a second producer. The CLI reads stdin through read_capped in src/cli/mod.rs, which reads at most one byte past MAX_INPUT_BYTES and returns InputTooLarge with what set to \"input\" before the bytes ever reach the engine. Same limit, same label, so a caller sees one gate however the text arrived. The CLI never decodes what it reads: the bytes go to the engine as Input::bytes, so an oversized pipe is reported as too large, and a pipe that is not UTF-8 is UnsupportedFormat, as a file's bytes would be.",
      "words": 94
    },
    {
      "compression_ratio": 0.4954,
      "kind": "paragraph",
      "lexical_density": 0.5224,
      "readability_grade": 7.2255,
      "sentences": 4,
      "text": "The four ranking methods check their caps after their empty-result checks. summarize_with(&doc, 0, ..) and keyphrases_with(&doc, 0, ..) return an empty result without evaluating the cap, whatever the size of the document. The same holds for a document with no sentences. clusters has no count parameter; its cap is checked first, before anything is embedded, then its contract, and a document with no sentences returns empty clusters.",
      "words": 68
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5227,
      "readability_grade": 14.7127,
      "sentences": 2,
      "text": "A metric has no gate of its own. The compression ratio skips any paragraph over 262,144 bytes (MAX_COMPRESSION_PARAGRAPH_BYTES) and leaves its metric slot at None rather than returning an error, and a paragraph under a metric's minimum word count (MIN_READABILITY_WORDS, MIN_COMPRESSION_WORDS) does the same.",
      "words": 45
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5,
      "readability_grade": 9.825,
      "sentences": 4,
      "text": "The call cannot be honored as made, and making it again as it is will fail the same way. The remedy is to change something the caller controls: the arguments, the configuration, the data handed in, or the embedder passed to clusters. Nothing about analysed text produces it.",
      "words": 49
    },
    {
      "compression_ratio": 0.5685,
      "kind": "paragraph",
      "lexical_density": 0.6,
      "readability_grade": 9.7133,
      "sentences": 3,
      "text": "One kind covers every such check, because they share that remedy, and reason says which check failed: a stable snake_case name, in details[\"reason\"] on every channel, to branch on where the remedy differs. message names the values that failed it, for a person. A reader treats the set of reasons as open, since a later version can add a check.",
      "words": 61
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5714,
      "readability_grade": 14.2943,
      "sentences": 1,
      "text": "A config file that is simply absent is not an error for Config::resolve, and the built-in defaults stand; Config::from_file refuses one with Io, because the caller named it.",
      "words": 32
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.6667,
      "readability_grade": null,
      "sentences": 1,
      "text": "Returned by Engine::analyze in two cases:",
      "words": 7
    },
    {
      "compression_ratio": 0.5225,
      "kind": "list_item",
      "lexical_density": 0.5217,
      "readability_grade": 10.0556,
      "sentences": 5,
      "text": "The engine has no reader for the input's format: Pdf or Docx, whether named by the caller, read off the extension, or recognised from the bytes (%PDF, or a zip archive holding [Content_Types].xml, which outranks the extension), or a Format::Other the caller named and registered no reader for. format is that format, and feature names the Cargo feature that would read it; no feature of this version reads any of them, so feature is None. A reader registered with Engine::with_reader reads any of them. Markdown, PlainText and Blocks always have a reader.",
      "words": 96
    },
    {
      "compression_ratio": null,
      "kind": "list_item",
      "lexical_density": 0.5122,
      "readability_grade": 7.2961,
      "sentences": 3,
      "text": "The bytes are not UTF-8 text and carry no signature matra recognises. format and feature are both None. This used to be Io with kind InvalidData; nothing went wrong reading the bytes, so it is now a kind with a remedy.",
      "words": 42
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.4737,
      "readability_grade": 6.1042,
      "sentences": 1,
      "text": "A UTF-8 file with an extension matra does not know is not this error: it reads as plain text.",
      "words": 20
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.75,
      "readability_grade": null,
      "sentences": 1,
      "text": "Wraps std::io::Error, produced by:",
      "words": 6
    },
    {
      "compression_ratio": null,
      "kind": "list_item",
      "lexical_density": 0.6207,
      "readability_grade": 10.5593,
      "sentences": 2,
      "text": "Reading a file rejecting a symlink, with ErrorKind::Unsupported and the message refusing to read symlink: <path>; Inputs::dir refuses a symlinked directory the same way. The path is also details.path.",
      "words": 31
    },
    {
      "compression_ratio": null,
      "kind": "list_item",
      "lexical_density": 0.5405,
      "readability_grade": 11.2254,
      "sentences": 2,
      "text": "Reading a file rejecting a path that is neither a regular file nor a directory, with ErrorKind::InvalidInput and the message not a regular file: <path>, and the path in details.path. A directory is InvalidInput instead, naming Inputs::dir.",
      "words": 39
    },
    {
      "compression_ratio": null,
      "kind": "list_item",
      "lexical_density": 0.8182,
      "readability_grade": 10.1545,
      "sentences": 1,
      "text": "Any read, directory listing, directory creation, write, or rename that fails.",
      "words": 11
    },
    {
      "compression_ratio": 0.5581,
      "kind": "list_item",
      "lexical_density": 0.5588,
      "readability_grade": 9.1493,
      "sentences": 4,
      "text": "The UDPipe provisioner when a download fails at the transport or answers with a non-2xx status. Same shape as the embedding path below: the message names the URL, and the kind is TimedOut past the 300-second fetch budget or the 30-second connect budget, NotConnected for an unreachable host, and whatever the socket reported otherwise. The URL is also details.url, and details.retryable is true, except for a rejected certificate.",
      "words": 73
    },
    {
      "compression_ratio": 0.5323,
      "kind": "list_item",
      "lexical_density": 0.5758,
      "readability_grade": 8.7238,
      "sentences": 4,
      "text": "The UDPipe provisioner when the model directory cannot be created, or when the verified bytes cannot be written or renamed into place. The message names the operation and the path, so a full disk reads cannot write the model to <path>: No space left on device (os error 28) rather than Permission denied (os error 13) with nothing to act on. The path is also details.path.",
      "words": 71
    },
    {
      "compression_ratio": 0.566,
      "kind": "list_item",
      "lexical_density": 0.5395,
      "readability_grade": 11.2279,
      "sentences": 4,
      "text": "Model2Vec::potion_base_8m when a download fails at the transport or answers with a non-2xx status. The message names the URL, and the kind is TimedOut past the 300-second fetch budget or the 30-second connect budget, NotConnected for an unreachable host, and whatever the socket reported otherwise. The URL and retryable are details, as on the UDPipe path. Bytes that arrived and then failed the digest are ModelInvalid instead; this variant is for the ones that never arrived.",
      "words": 81
    },
    {
      "compression_ratio": 0.5476,
      "kind": "list_item",
      "lexical_density": 0.5283,
      "readability_grade": 10.9511,
      "sentences": 3,
      "text": "Model2Vec::potion_base_8m when the model directory cannot be created, when an artifact cannot be read, or when a verified artifact cannot be written or renamed into place. The message names the operation and the path, exactly as the UDPipe path's does, and the path is details.path. Model2Vec::from_dir reports an unreadable artifact the same way.",
      "words": 57
    },
    {
      "compression_ratio": null,
      "kind": "list_item",
      "lexical_density": 0.5208,
      "readability_grade": 15.1575,
      "sentences": 2,
      "text": "Model2Vec::potion_base_8m when the temporary file an artifact lands through cannot be created, with the kind the open reported (AlreadyExists when something is already sitting at that path). The temporary is opened exclusively, so a path already there, symlink or not, fails the open rather than being written through.",
      "words": 50
    },
    {
      "compression_ratio": null,
      "kind": "list_item",
      "lexical_density": 0.5882,
      "readability_grade": 16.0282,
      "sentences": 1,
      "text": "Engine::analyze when reading a file yields no document, with ErrorKind::InvalidData and the message source returned no documents.",
      "words": 19
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5,
      "readability_grade": 13.2463,
      "sentences": 2,
      "text": "The UDPipe provisioner (behind Engine::new and Engine::from_config, in Rust and Python) and Model2Vec::potion_base_8m obtain a pinned artifact over the network. Both fetch through matra's own client, under the same bounds, and both classify a failure the same way.",
      "words": 42
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5556,
      "readability_grade": 9.7787,
      "sentences": 2,
      "text": "The rule behind the table: model_invalid is about bytes that arrived. Anything that stopped a fetch from arriving, or a filesystem from accepting it, is io (RFC-0015).",
      "words": 28
    },
    {
      "compression_ratio": 0.5827,
      "kind": "paragraph",
      "lexical_density": 0.451,
      "readability_grade": 6.7733,
      "sentences": 3,
      "text": "retryable is true when the same call can be made again as it is and may succeed. A failed fetch writes nothing, so a retry starts from where the first call did. A rejected certificate is false: a retry meets the same proxy, and the message names the way out instead.",
      "words": 51
    },
    {
      "compression_ratio": 0.5262,
      "kind": "paragraph",
      "lexical_density": 0.5053,
      "readability_grade": 8.7071,
      "sentences": 5,
      "text": "The rule has a consequence in Python that is easy to miss, because it changes which except clause fires rather than only which string a message carries. IoError is an OSError and ModelInvalidError is a RuntimeError, so from 0.2.0 a DNS failure, a rejected certificate, a timeout or a non-2xx status raises an OSError from the call that builds the engine, where it used to raise RuntimeError. A caller that wrapped a bootstrap in except RuntimeError catches nothing now and the OSError propagates past it. Catch matra.MatraError, which both derive from, and branch on kind.",
      "words": 97
    },
    {
      "compression_ratio": 0.4446,
      "kind": "paragraph",
      "lexical_density": 0.5459,
      "readability_grade": 14.0732,
      "sentences": 8,
      "text": "Nothing that failed the digest is ever written. Both provisioners fetch into memory, verify there, and write only what verified, so a download that fails adds nothing to the model directory and a run killed mid-transfer leaves nothing at all. A failed run removes nothing either. A cached file that is already there and fails verification is not loaded and not deleted: the UDPipe provisioner downloads again, at most twice, and replaces the file only with bytes that verified, through the same atomic rename every install lands through. A run whose downloads fail, at the network or at the digest, leaves that file byte-identical. Model2Vec::potion_base_8m replaces nothing and refuses a directory whose artifacts fail verification, because its three filenames belong to the artifact format rather than to this one model and so may be a caller's own (RFC-0015). A temporary left by a killed process is reclaimed by the next download that finds it older than ten minutes, which is twice the fetch budget and therefore older than any transfer that could still be running. The UDPipe provisioner leaves a temporary directory and Model2Vec::potion_base_8m three temporary files, and each reclaims its own by the same rule.",
      "words": 198
    },
    {
      "compression_ratio": 0.5748,
      "kind": "paragraph",
      "lexical_density": 0.6333,
      "readability_grade": 25.51,
      "sentences": 2,
      "text": "matra verifies TLS against root certificates compiled into the binary and never reads the system trust store, so a proxy that re-signs TLS cannot be made trusted. The fetch fails as Io, kind io, and the message names the host, says why its certificate cannot be trusted, names the file to fetch by hand, and ends with the underlying failure:",
      "words": 62
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.6,
      "readability_grade": 8.37,
      "sentences": 1,
      "text": "Install the model behind a TLS-intercepting proxy has the steps.",
      "words": 11
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.4783,
      "readability_grade": 9.5409,
      "sentences": 2,
      "text": "A cold run has to fetch 16.3 MB before it can answer, and how long that takes is the link's business rather than matra's. The command line writes two lines to standard error before the transfer and nothing at all when the model is already there:",
      "words": 48
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.4483,
      "readability_grade": 12.4028,
      "sentences": 1,
      "text": "The second line is there because the model is a separate file with its own license, which is not matra's MIT; model licenses has both models and their sources.",
      "words": 30
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.625,
      "readability_grade": 11.0638,
      "sentences": 3,
      "text": "Standard error, so --json output stays a single object on standard output. --quiet silences it. A library caller gets the same facts as a domain::ProvisionNotice from Engine::from_config_with_notice, and decides the wording itself.",
      "words": 34
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5909,
      "readability_grade": 8.0082,
      "sentences": 2,
      "text": "The first matra clusters says the same for the embedding model, whose three files are fetched as one set of 30.9 MB:",
      "words": 22
    },
    {
      "compression_ratio": 0.4741,
      "kind": "paragraph",
      "lexical_density": 0.5968,
      "readability_grade": 13.697,
      "sentences": 3,
      "text": "Python writes the same two lines to sys.stderr before Engine(), Engine.from_config(), Model2Vec.potion_base_8m() or Model2Vec.from_config() downloads; redirect sys.stderr to silence them. A Rust caller gets the facts from Engine::from_config_with_notice and Model2Vec::from_config_with_notice and chooses the wording, since the library writes to no terminal. The other Rust constructors, Engine::new, Engine::from_config, Model2Vec::potion_base_8m and Model2Vec::from_config, take no notice and say nothing for the length of their download.",
      "words": 70
    },
    {
      "compression_ratio": 0.5493,
      "kind": "paragraph",
      "lexical_density": 0.5857,
      "readability_grade": 12.39,
      "sentences": 4,
      "text": "The stream surface never lets one bad document abort the rest. Engine::analyze_all yields Result<Document, DocumentError> per input, where DocumentError pairs the Error with the path it occurred at (None for an input that is not a file, so a path-less document is distinguishable from one at an empty path). Its Display prints path: error when a path exists and the bare error otherwise, and its source() is the wrapped Error.",
      "words": 74
    },
    {
      "compression_ratio": 0.5987,
      "kind": "paragraph",
      "lexical_density": 0.6122,
      "readability_grade": 13.9528,
      "sentences": 2,
      "text": "The stream yields one item per input, in order: the Document, or the DocumentError in its place, so documents plus errors equals inputs consumed, and partitioning them is the caller's. Inputs::dir is Err only when the listing itself fails; both read failures and analysis failures travel as stream items.",
      "words": 51
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5625,
      "readability_grade": 8.8417,
      "sentences": 3,
      "text": "Two kinds of entry never appear on either side. The directory listing skips symlinks, so a symlink produces no document and no error. It also skips anything that is not a regular file, and the walk is one level deep, so a subdirectory is skipped the same way.",
      "words": 48
    },
    {
      "compression_ratio": 0.5138,
      "kind": "paragraph",
      "lexical_density": 0.5931,
      "readability_grade": 7.3293,
      "sentences": 10,
      "text": "DocumentError serializes as its error's form plus the path: {\"path\", \"kind\", \"message\", \"details\"}, with path null for input that never came from disk. Python's Engine.analyze_all yields that form as a dict for each failed document. kind is the stable string Error::kind names for the variant, and the table below carries all seven. Error::kind is a match with no wildcard arm, so a new Error variant fails to compile until someone names it, and spec/tests/corpus/items.json pins the vocabulary with a runner per crust, so every crust spells a failure the same way. Both item shapes come from serde. Either's path (provenance.source.path on a document, path on an error) is decoded with os.fsdecode, so os.fsencode on it names the file the walk read even when that name is not valid UTF-8. The Python call yields the items in order and the caller partitions them, testing isinstance(item, matra.Document).",
      "words": 154
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5306,
      "readability_grade": 9.3229,
      "sentences": 3,
      "text": "Error::details returns an ErrorDetails: the values a caller acts on, by name, which for every kind but invalid_input is every dynamic value in the message. Each value is a DetailValue, which is text, a whole number or a boolean. A caller reads a value instead of parsing the message.",
      "words": 50
    },
    {
      "compression_ratio": 0.558,
      "kind": "list_item",
      "lexical_density": 0.5714,
      "readability_grade": 10.3937,
      "sentences": 3,
      "text": "One word, one meaning. reason is always the name of a check that failed, stable and snake_case, to branch on: on invalid_input always, and on parse_failed when the engine's checks refused what a parser or a reader returned. cause is always free text for a person, like the message: the text the variant holds, or the operating system's account of an I/O failure.",
      "words": 66
    },
    {
      "compression_ratio": null,
      "kind": "list_item",
      "lexical_density": 0.7429,
      "readability_grade": 20.6514,
      "sentences": 3,
      "text": "io_kind is the I/O failure's class in snake case: not_found, permission_denied, already_exists, unsupported, invalid_input, invalid_data, timed_out, not_connected, connection_refused, connection_reset, unexpected_eof, interrupted, not_a_directory, is_a_directory or storage_full. Any other class is other. Treat the set as open.",
      "words": 37
    },
    {
      "compression_ratio": null,
      "kind": "list_item",
      "lexical_density": 0.5294,
      "readability_grade": 5.0779,
      "sentences": 2,
      "text": "retryable appears only on a download that did not arrive. Its absence makes no claim either way.",
      "words": 18
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5306,
      "readability_grade": 7.878,
      "sentences": 3,
      "text": "A detail that does not apply is absent, never empty: an unsupported_format for bytes that are not text carries no details at all. A key a kind carries keeps appearing in later versions. A later version may add keys, so read the ones you know and ignore the rest.",
      "words": 49
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.7143,
      "readability_grade": null,
      "sentences": 1,
      "text": "The serde form is {\"kind\", \"message\", \"details\"}:",
      "words": 7
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5,
      "readability_grade": 8.3833,
      "sentences": 1,
      "text": "spec/schema/v2/error.schema.json is the published JSON Schema for this form and for DocumentError's, with the keys each kind carries.",
      "words": 19
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5135,
      "readability_grade": 8.2088,
      "sentences": 2,
      "text": "These are the strings Display produces, which are also the strings Python's str(exc) returns, alongside the kind Error::kind reports for each variant. A message is for a human to read; a kind is what code branches on.",
      "words": 40
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.6667,
      "readability_grade": 12.2667,
      "sentences": 1,
      "text": "UnsupportedFormat renders the format's wire name, so the string reads unsupported format: pdf; no feature of this matra version reads it.",
      "words": 22
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5,
      "readability_grade": 11.47,
      "sentences": 1,
      "text": "The details carry the same values without a match on the variant, which is what a caller forwarding an error to another program wants:",
      "words": 24
    },
    {
      "compression_ratio": 0.5574,
      "kind": "paragraph",
      "lexical_density": 0.5432,
      "readability_grade": 6.9871,
      "sentences": 5,
      "text": "The PyO3 binding raises each Error as a class of its own, named for the variant with PEP 8's Error suffix. The name a failure shares across languages is its kind, not its class. Every class derives from matra.MatraError and from the builtin class matra raised before 0.3.0, so except ValueError still catches an InputTooLargeError. The routing is a match with no wildcard arm over the variants, so adding a variant to Error without assigning it a class fails to compile.",
      "words": 83
    },
    {
      "compression_ratio": 0.5414,
      "kind": "paragraph",
      "lexical_density": 0.5192,
      "readability_grade": 8.44,
      "sentences": 6,
      "text": "Io routes on the I/O kind it wraps. A missing file is an IoNotFoundError, which is a FileNotFoundError; a refused permission is an IoPermissionError, which is a PermissionError. Both derive from IoError, so except matra.IoError catches all three. matra.IoError is matra's class, not the builtin IOError, which is another name for OSError.",
      "words": 54
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5682,
      "readability_grade": 17.3927,
      "sentences": 2,
      "text": "Every exception carries the same three things as the serde form: kind, the string Error::kind names; details, a dict of the details; and the Display string as its message, which str(exc) returns. Branch on the class or on kind, and read values from details:",
      "words": 46
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.6,
      "readability_grade": null,
      "sentences": 1,
      "text": "IoNotFoundError is a FileNotFoundError, so the conventional Python idiom works:",
      "words": 10
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5455,
      "readability_grade": 9.0818,
      "sentences": 2,
      "text": "The classes name matra as their module, so a traceback reads matra.InputTooLargeError, and an exception survives pickle with its kind and details.",
      "words": 22
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.6304,
      "readability_grade": 11.08,
      "sentences": 2,
      "text": "Every Python input reaches the parser through the engine's reading stage, so the 8 MiB \"input\" gate applies uniformly, to text, bytes and blocks alike, and a file meets \"file_read\" first. The outcome functions take a Document, never text, and their own caps apply to it.",
      "words": 47
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.6136,
      "readability_grade": 7.7409,
      "sentences": 4,
      "text": "One further failure has no Error variant behind it. Python's Engine is #[pyclass(unsendable)], because the loaded model holds C-side state that is not thread-safe. Accessing one engine from a thread other than the one that created it fails at runtime. Multi-process use is unaffected.",
      "words": 49
    },
    {
      "compression_ratio": 0.586,
      "kind": "paragraph",
      "lexical_density": 0.5577,
      "readability_grade": 9.5508,
      "sentences": 3,
      "text": "One program is installed under the name matra, by either of two routes. The Rust binary comes from cargo install matra --features cli; the Python console script comes from the wheel and calls the same matra::cli::run through the extension module. The exit-code contract below is the program's, so it holds on both.",
      "words": 56
    },
    {
      "compression_ratio": 0.5277,
      "kind": "paragraph",
      "lexical_density": 0.5802,
      "readability_grade": 12.8585,
      "sentences": 3,
      "text": "On exit code 2 the command writes matra:  followed by the error's Display string to standard error, prefixed with the path when the failure concerns a file. Under --json it also writes the envelope to standard output, with result null and error holding the serde form above, {kind, message, details}: the same three a Rust caller serializes and a Python caller reads off the exception. The envelope's input names the file, so the error object carries no path of its own.",
      "words": 83
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5667,
      "readability_grade": 9.14,
      "sentences": 1,
      "text": "spec/tests/parity/parity.json pins that equality: the same files through Rust, Python and the command line give the same kind, message and details, and a runner per surface fails on a drift.",
      "words": 31
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5833,
      "readability_grade": 4.8233,
      "sentences": 1,
      "text": "A broken pipe, which is what happens when the reading end of matra analyze file.md | head goes away, exits 0 and prints nothing.",
      "words": 24
    },
    {
      "compression_ratio": 0.5673,
      "kind": "paragraph",
      "lexical_density": 0.5714,
      "readability_grade": 9.8317,
      "sentences": 3,
      "text": "matra analyze DIR reads every file in the directory and keeps going past a failure. Each failed file is a line on standard error and, under --json, its own envelope line with its error; the run exits 2 if any file failed, after the walk has finished. This is the one partial success the command line has: per-item failure in a bulk operation.",
      "words": 63
    },
    {
      "compression_ratio": 0.5132,
      "kind": "paragraph",
      "lexical_density": 0.5436,
      "readability_grade": 16.1227,
      "sentences": 4,
      "text": "The table is the whole contract, and no command narrows it. The command line's own refusals carry the kind whose remedy matches, which for each of them is InvalidInput, a call to change: a directory given to summarize, keyphrases or clusters, --format with a directory, matra --skill -r <name> or matra --schema <name> with a name nothing answers to (both name the ones that exist), -r without --skill, config init over an existing file without --force, clusters in a build without the model2vec feature, and a usage error such as an unknown flag. A missing path is not one of them: it is the library's own Io failure with not_found, raised before the engine is built so it costs no model load. matra --skill and matra --schema in any of their accepted forms exit 0; they read no document, so they have nothing to find and never exit 1.",
      "words": 151
    },
    {
      "compression_ratio": null,
      "kind": "paragraph",
      "lexical_density": 0.5455,
      "readability_grade": 13.3718,
      "sentences": 2,
      "text": "The exception classes above belong to the library surface, not to the command line. A domain::Error reaching the command line is rendered and turned into an exit code and, under --json, an envelope; it never surfaces as a Python exception, whichever launcher started it.",
      "words": 45
    }
  ]
}
