feat(domain): R4.2 scaffold of the pdf reader module (feature pdf-read, miniz_oxide)

Module layout of plan §B.1.1 for the reader (read/{scan,strings,stamp,inflate,probe},
json_js), shared constants and types, index_of; feature-gated test targets; the wasm
facade enables the feature; rust-check runs the gated clippy and tests.
This commit is contained in:
bchanot committed 2026-10-18 15:29:58 +02:00
1 parent c6bf175b61
commit 21d34fb9a7
18 files changed
+166 -1

No files matched your search

+2
View File
@@ -10,6 +10,8 @@ pub mod domain;
pub mod facade;
pub mod json;
pub mod ops;
#[cfg(feature = "pdf-read")]
pub mod pdf;
/// Version of the core, reported by the wasm facade and the worker.
pub const CORE_VERSION: &str = env!("CARGO_PKG_VERSION");
+1
View File
@@ -0,0 +1 @@
//! R4.2c: the JavaScript-path JSON side effects of the import. Written by the R4.2c track.
+10
View File
@@ -0,0 +1,10 @@
//! The PDF side of the core (R4, plan `.claude/tasks/plans/2026-10-17-rust-r4-pdf-core.md`).
//!
//! R4.2 brings the reader: the attachment located by a byte scan over the file (never a parse
//! of the object graph, BLK-009), inflated under a cap, probed as JSON, then handed to the
//! R2 session import. Every rule is the one `packages/pdf/src/attachment/scan.ts` applied,
//! pinned by the frozen oracles O7 (`tests/oracles/r4/read.json`), O8 (`tolerance.json`) and
//! O9 (`inflate.json`). The writer (`write`) and the import entry (`import`) follow.
pub mod json_js;
pub mod read;
+1
View File
@@ -0,0 +1 @@
//! R4.2b: `inflateFlate` of inflate.ts on miniz_oxide. Written by the R4.2b track.
+88
View File
@@ -0,0 +1,88 @@
//! Locating the Faunosteo attachment in a PDF's bytes (port of
//! `packages/pdf/src/attachment/{scan,inflate,read}.ts`, plan §B.1.2).
//!
//! A stream object can never live inside an object stream, so every `/Type /EmbeddedFile`
//! dictionary and its data are in clear in the file. Nothing here parses the object graph,
//! the xref or an `/ObjStm`: the only inflation on the import path is the capped one of
//! [`inflate::inflate_flate`]. The scanner never fails on garbage: it returns fewer
//! candidates. Every loop is bounded by the file end, itself capped at [`MAX_PDF_BYTES`].
//!
//! The TypeScript relied on JavaScript regular expressions in a few places; their exact
//! semantics (which bytes `\s` matches, lazy `/EF` removal, `.` excluding CR and LF in a
//! string token) are reproduced explicitly and pinned by the `semantics.*` rows of O7.
pub mod inflate;
pub mod probe;
pub mod scan;
pub mod stamp;
pub mod strings;
/// A Faunosteo PDF weighs a few hundred KB; anything larger is not one.
pub const MAX_PDF_BYTES: usize = 50 * 1024 * 1024;
/// Hard ceiling on an attachment, inflated or not: a report archive weighs a few hundred KB;
/// anything bigger is a decompression bomb or corruption.
pub const MAX_ATTACHMENT_BYTES: usize = 16 * 1024 * 1024;
/// The file name prefix every Faunosteo attachment carries.
pub const ATTACHMENT_NAME_PREFIX: &str = "osteo-report";
/// The keyword stamp every archive carries (`faunosteo-archive/<n>`).
pub const ARCHIVE_STAMP: &str = "faunosteo-archive";
/// Candidates beyond this count are ignored: a crafted file cannot make the reader loop.
pub const MAX_CANDIDATES: usize = 32;
/// A stream or Filespec dictionary is small; a longer one is skipped.
pub const MAX_DICT_BYTES: usize = 4096;
/// The stream filter the scanner recognises.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StreamFilter {
/// `/FlateDecode`, alone or first in an array.
FlateDecode,
/// Anything else, or no filter: the data is used raw.
None,
}
/// An `/EmbeddedFile` stream found in clear.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EmbeddedFileCandidate {
/// First byte of the stream data.
pub offset: usize,
/// Byte count of the stream data (declared, or measured to `endstream`).
pub length: usize,
pub filter: StreamFilter,
/// From a visible `/Filespec` whose `/EF /F` points at this stream, decoded as text
/// (UTF-16BE with BOM, else Latin-1); a lone surrogate becomes U+FFFD.
pub name: Option<String>,
}
/// Why no attachment comes out of a file (`ArchiveReadErrorKind` of the TypeScript).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReadKind {
/// Over [`MAX_PDF_BYTES`], or no `%PDF-` within the first KiB.
InvalidPdf,
/// No candidate holds a versioned JSON object, and no archive stamp is visible.
NoAttachment,
/// No candidate holds a versioned JSON object, but a `/Keywords` string carries the
/// archive stamp: the attachment was stripped by another tool.
AttachmentStripped,
}
impl ReadKind {
/// The closed kind name the facade and the messages use.
pub fn as_str(self) -> &'static str {
match self {
Self::InvalidPdf => "invalid_pdf",
Self::NoAttachment => "no_attachment",
Self::AttachmentStripped => "attachment_stripped",
}
}
}
/// `%PDF-` within the first KiB, as viewers accept it.
pub fn has_pdf_header(bytes: &[u8]) -> bool {
let end = bytes.len().min(1024);
scan::index_of(bytes, b"%PDF-", 0, end).is_some()
}
+1
View File
@@ -0,0 +1 @@
//! R4.2d: `locateAttachment` of scan.ts. Written after R4.2a, b and c.
+22
View File
@@ -0,0 +1,22 @@
//! R4.2a: `findEmbeddedFiles` of scan.ts (header, typed dictionaries, stream bounds,
//! Filespec names). Written by the R4.2a track; `index_of` is shared by the other files.
/// Naive forward search of `needle` in `bytes[from..end]`; the needle's first byte is the
/// fast reject (scan.ts `indexOf`). `None` when absent or when the window is shorter than
/// the needle.
pub fn index_of(bytes: &[u8], needle: &[u8], from: usize, end: usize) -> Option<usize> {
let end = end.min(bytes.len());
if needle.is_empty() || end < needle.len() {
return None;
}
let last = end - needle.len();
let first = needle[0];
let mut i = from;
while i <= last {
if bytes[i] == first && bytes[i..i + needle.len()] == *needle {
return Some(i);
}
i += 1;
}
None
}
+1
View File
@@ -0,0 +1 @@
//! R4.2a: `hasArchiveStamp` of scan.ts. Written by the R4.2a track.
+1
View File
@@ -0,0 +1 @@
//! R4.2a: `decodePdfString` of scan.ts. Written by the R4.2a track.