flpdf 0.10.0

A pure-Rust PDF toolkit modeled on qpdf — read, rewrite, linearize, and inspect PDFs.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
//! Byte-identity demonstration: flpdf linearized output ==
//! `qpdf --linearize --deterministic-id`.
//!
//! This pins flpdf's linearized + deterministic-`/ID` writer to the committed
//! qpdf golden references at `tests/golden/references/<stem>/linearize.pdf`
//! (produced by qpdf 11.9.0; see `tests/golden/regenerate.sh`). It is gated on
//! the `qpdf-zlib-compat` feature because byte-identity requires flpdf's deflate
//! output to match qpdf's classic-libz output (the Pure-Rust miniz_oxide default
//! produces equivalent but not byte-identical compression).
//!
//! The public-API sequence mirrors the CLI's `--linearize` path: build the
//! [`LinearizationPlan`] and [`RenumberMap`] from one handle, then re-open the
//! file so [`write_linearized`] can seek/read objects independently, write with
//! `deterministic_id` set, and `back_patch` the param-dict placeholders, `/Prev`,
//! and `/ID`.
//!
//! CAVEAT: byte-identity pins to the linked libz version (captured with zlib1g
//! 1:1.3.dfsg-3.1ubuntu2.1 / qpdf 11.9.0); a different libz may shift the deflate
//! bytes and require re-blessing the goldens.

#![cfg(feature = "qpdf-zlib-compat")]

use flpdf::{CompressStreams, EncryptParams, NewlineBeforeEndstream, ObjectStreamMode, Pdf};
use std::path::Path;
use std::process::Command;

/// Linearize `fixture` via the public API (mirroring the CLI `--linearize`
/// path) and return the complete back-patched bytes.
fn flpdf_linearized(fixture: &str) -> Vec<u8> {
    let path = Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("../../tests/fixtures/compat")
        .join(fixture);

    flpdf_linearized_at(&path)
}

/// As [`flpdf_linearized`], but for an input written during the test rather
/// than a committed fixture.
fn flpdf_linearized_at(path: &Path) -> Vec<u8> {
    let file = std::fs::File::open(path).unwrap_or_else(|e| panic!("open {path:?}: {e}"));
    let mut pdf = Pdf::open(std::io::BufReader::new(file)).unwrap();
    let opts = WriterTestSettings {
        deterministic_id: true,
        // qpdf's default output writes no newline before endstream; the linearized
        // body content streams honour this option (see the plain-path sibling in
        // `cmp_diff_zero_tests`).
        newline_before_endstream: NewlineBeforeEndstream::Never,
        ..WriterTestSettings::default()
    };

    write_linearized_with_settings(&mut pdf, &opts).unwrap()
}

/// As [`flpdf_linearized`], but opens the fixture with `open_with_repair` so an
/// input whose xref must be reconstructed still parses. Both the plan handle and
/// the write handle repair independently (each re-opens the file).
fn flpdf_linearized_repair(fixture: &str) -> Vec<u8> {
    let path = Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("../../tests/fixtures/compat")
        .join(fixture);

    let file = std::fs::File::open(&path).unwrap_or_else(|e| panic!("open {path:?}: {e}"));
    let mut pdf = Pdf::open_with_repair(std::io::BufReader::new(file)).unwrap();
    let opts = WriterTestSettings {
        deterministic_id: true,
        newline_before_endstream: NewlineBeforeEndstream::Never,
        ..WriterTestSettings::default()
    };
    write_linearized_with_settings(&mut pdf, &opts).unwrap()
}

fn golden(fixture_stem: &str) -> Vec<u8> {
    let path = Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("../../tests/golden/references")
        .join(fixture_stem)
        .join("linearize.pdf");
    std::fs::read(&path).unwrap_or_else(|e| panic!("read golden {path:?}: {e}"))
}

fn golden_classic(fixture_stem: &str) -> Vec<u8> {
    let path = Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("../../tests/golden/references")
        .join(fixture_stem)
        .join("linearize-classic.pdf");
    std::fs::read(&path).unwrap_or_else(|e| panic!("read golden {path:?}: {e}"))
}

/// Report the first differing byte offset for a readable failure message.
fn first_diff(a: &[u8], b: &[u8]) -> Option<usize> {
    if a == b {
        return None;
    }
    let common = a.len().min(b.len());
    for i in 0..common {
        if a[i] != b[i] {
            return Some(i);
        }
    }
    Some(common)
}

fn assert_linearize_byte_identical(fixture: &str, stem: &str) {
    let actual = flpdf_linearized(fixture);
    let expected = golden(stem);
    if let Some(off) = first_diff(&actual, &expected) {
        let lo = off.saturating_sub(16);
        panic!(
            "{fixture}: not byte-identical to qpdf --linearize --deterministic-id golden \
             (flpdf={} bytes, golden={} bytes, first diff at byte {off})\n\
             flpdf : {:?}\ngolden: {:?}",
            actual.len(),
            expected.len(),
            &actual[lo..(off + 16).min(actual.len())],
            &expected[lo..(off + 16).min(expected.len())],
        );
    }
}

/// As [`assert_linearize_byte_identical`], but drives the writer via
/// [`flpdf_linearized_repair`] for a fixture whose xref must be reconstructed.
fn assert_linearize_byte_identical_repair(fixture: &str, stem: &str) {
    let actual = flpdf_linearized_repair(fixture);
    let expected = golden(stem);
    if let Some(off) = first_diff(&actual, &expected) {
        let lo = off.saturating_sub(16);
        panic!(
            "{fixture}: not byte-identical to qpdf --linearize --deterministic-id golden \
             (flpdf={} bytes, golden={} bytes, first diff at byte {off})\n\
             flpdf : {:?}\ngolden: {:?}",
            actual.len(),
            expected.len(),
            &actual[lo..(off + 16).min(actual.len())],
            &expected[lo..(off + 16).min(expected.len())],
        );
    }
}

fn assert_classic_byte_identical(fixture: &str, stem: &str) {
    let actual = flpdf_linearized(fixture);
    let expected = golden_classic(stem);
    if let Some(off) = first_diff(&actual, &expected) {
        let lo = off.saturating_sub(16);
        panic!(
            "{fixture}: not byte-identical to qpdf --linearize --deterministic-id golden \
             (flpdf={} bytes, golden={} bytes, first diff at byte {off})\n\
             flpdf : {:?}\ngolden: {:?}",
            actual.len(),
            expected.len(),
            &actual[lo..(off + 16).min(actual.len())],
            &expected[lo..(off + 16).min(expected.len())],
        );
    }
}

fn assert_classic_structurally_byte_identical(fixture: &str, stem: &str) {
    let actual = mask_id1(&flpdf_linearized(fixture));
    let expected = mask_id1(&golden_classic(stem));
    if let Some(off) = first_diff(&actual, &expected) {
        let lo = off.saturating_sub(16);
        panic!(
            "{fixture}: structural layout diverged from qpdf classic golden (ignoring /ID[1]) \
             (flpdf={} bytes, golden={} bytes, first diff at byte {off})\n\
             flpdf : {:?}\ngolden: {:?}",
            actual.len(),
            expected.len(),
            &actual[lo..(off + 16).min(actual.len())],
            &expected[lo..(off + 16).min(expected.len())],
        );
    }
}

/// Return the pinned qpdf 11.9.0 binary, or `None` when it is unavailable.
///
/// A differently versioned qpdf on `PATH` is deliberately rejected: this
/// comparison claims 11.9.0 parity, so another release would silently change
/// the oracle rather than the expectation.
fn pinned_qpdf() -> Option<&'static str> {
    let output = Command::new("qpdf").arg("--version").output();
    output.ok().and_then(|output| {
        String::from_utf8_lossy(&output.stdout)
            .lines()
            .next()
            .is_some_and(|line| line == "qpdf version 11.9.0")
            .then_some("qpdf")
    })
}

/// qpdf writes the complete `/Pages` user set at the head of part 9, ahead of
/// thumbnails, outlines and the remaining `lc_other` set, by erasing each
/// page-tree node from `lc_other` and pushing it first
/// (`QPDF_linearization.cc:1279-1290`). A page-tree node therefore precedes a
/// preserved object stream even when that stream's source object number is
/// lower.
///
/// The committed fixture does not reach the conflicting layout on its own: its
/// page tree already outranks the object stream. qpdf's own rewrite renumbers
/// the page tree above the stream, so the input is produced here rather than
/// committed.
#[test]
fn part9_pages_precede_lower_numbered_preserved_objstm() {
    let Some(oracle) = pinned_qpdf() else {
        eprintln!("[SKIP cmp_linearize_tests] qpdf 11.9.0 is unavailable");
        return;
    };
    let fixture = Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("../../tests/fixtures/compat")
        .join("preserve-pages-source-order-conflict.pdf");
    let directory = tempfile::tempdir().expect("tempdir");

    let rewritten = directory.path().join("rewritten.pdf");
    let status = Command::new(oracle)
        .args(["--static-id", "--warning-exit-0"])
        .arg(&fixture)
        .arg(&rewritten)
        .status()
        .expect("qpdf runs");
    assert_eq!(status.code(), Some(0), "qpdf rewrite must succeed");

    let expected_path = directory.path().join("qpdf.pdf");
    let status = Command::new(oracle)
        .args(["--linearize", "--deterministic-id", "--warning-exit-0"])
        .arg(&rewritten)
        .arg(&expected_path)
        .status()
        .expect("qpdf runs");
    assert_eq!(status.code(), Some(0), "qpdf linearization must succeed");

    let actual = flpdf_linearized_at(&rewritten);
    let expected = std::fs::read(&expected_path).expect("qpdf output");
    if let Some(off) = first_diff(&actual, &expected) {
        panic!(
            "the page tree must precede the lower-numbered preserved object \
             stream (flpdf={} bytes, qpdf={} bytes, first diff at byte {off})",
            actual.len(),
            expected.len(),
        );
    }
}

/// qpdf writes the page tree at the head of part 9 and then the remaining
/// `lc_other` set in object order, so a preserved object stream anchors after
/// the ordinary `lc_other` object that precedes it rather than after the
/// promoted page tree (`QPDF_linearization.cc:1279-1290`).
///
/// `objstm-lin-part9-head-anchor.pdf` orders its part-9 `lc_other` set as
/// stream (obj 1), preserved object stream (obj 2), page tree (obj 8). Picking
/// the last qualifying predecessor instead of the greatest qualifying rank
/// puts the container directly after the page tree and changes the output.
#[test]
fn preserved_container_anchors_after_lc_other_not_the_promoted_page_tree() {
    assert_linearize_byte_identical(
        "objstm-lin-part9-head-anchor.pdf",
        "objstm-lin-part9-head-anchor",
    );
}

/// qpdf walks the page-tree user set as a `std::set<QPDFObjGen>` and writes it
/// at the head of part 9 (`QPDF_linearization.cc:1281-1290`), so that group
/// keeps its source object order even when one of its nodes lives inside a
/// preserved object stream.
///
/// `objstm-lin-part9-head-tiebreak.pdf` nests its page tree so the intermediate
/// node (obj 6) sits in the container (obj 2) while the root node (obj 8) stays
/// plain. Collapsing the head group to a single rank loses that order and emits
/// the root node before the container.
#[test]
fn part9_head_group_keeps_source_order_across_a_preserved_container() {
    assert_linearize_byte_identical(
        "objstm-lin-part9-head-tiebreak.pdf",
        "objstm-lin-part9-head-tiebreak",
    );
}

/// As above, but with plain page-tree nodes on both sides of the preserved
/// container: obj 5 and obj 12 stay plain while obj 7 holds obj 6, so qpdf's
/// `std::set` walk emits obj 5, then the container, then obj 12. A single
/// collapsed head rank puts the container ahead of obj 5 instead.
#[test]
fn part9_head_group_places_a_preserved_container_by_its_source_number() {
    assert_linearize_byte_identical(
        "objstm-lin-part9-head-container-order.pdf",
        "objstm-lin-part9-head-container-order",
    );
}

#[test]
fn one_page_linearized_is_byte_identical_to_qpdf() {
    assert_linearize_byte_identical("one-page.pdf", "one-page");
}

#[test]
fn two_page_linearized_is_byte_identical_to_qpdf() {
    assert_linearize_byte_identical("two-page.pdf", "two-page");
}

#[test]
fn three_page_linearized_is_byte_identical_to_qpdf() {
    assert_linearize_byte_identical("three-page.pdf", "three-page");
}

/// qpdf 11.9.0 has no writer/optimization nesting limit beyond its parser's
/// (`QPDFParser.cc:290`), so a 257-level direct `/Resources` array linearizes
/// like any other value; this pins the removal of flpdf's former 256-level
/// graph-walker cap byte-for-byte.
#[test]
fn deep_nesting_257_resources_linearized_is_byte_identical_to_qpdf() {
    assert_linearize_byte_identical(
        "deep-nesting-257-resources.pdf",
        "deep-nesting-257-resources",
    );
}

// A degenerate first page — the 3-object catalog/pages/page shape
// with NO /Contents and NO /Resources (no content stream, no inheritable
// resources to push down). The one/two/three-page corpus above all carry a page
// content stream, so this pins the no-stream shape that was previously
// uncovered. The primary hint stream's *uncompressed* bytes are already
// byte-identical to qpdf's for this shape (61 bytes, same content) — the encoder
// does not over-emit; the only delta on a default (miniz_oxide) build is the
// FlateDecode-*compressed* hint-stream size (qpdf 32 vs miniz 38 bytes, which
// shifts /L /E /T by 6), the sole sanctioned DEFLATE-backend deviation. Under
// qpdf-zlib-compat the compressed hint stream — and thus the whole file — is
// byte-identical to qpdf --linearize --deterministic-id, which this pins.
#[test]
fn no_stream_one_page_linearized_is_byte_identical_to_qpdf() {
    assert_linearize_byte_identical("no-stream-one-page.pdf", "no-stream-one-page");
}

#[test]
fn nonid_id0_linearized_is_byte_identical_to_qpdf() {
    // Non-16-byte (20-byte) source /ID[0] preserved verbatim on the linearized
    // path, byte-identical to qpdf --linearize --deterministic-id.
    assert_linearize_byte_identical("nonid-id0.pdf", "nonid-id0");
}

#[test]
fn indirect_extensions_linearized_is_byte_identical_to_qpdf() {
    assert_linearize_byte_identical(
        "linearize-indirect-extensions.pdf",
        "linearize-indirect-extensions",
    );
}

// The /Pages node holds a DIRECT /Resources dict (not a
// reference) and the /Page leaf has no local /Resources, so linearization
// must push the inherited /Resources down to the leaf (minting a fresh
// indirect object for the copy) and strip it from the now-interior /Pages
// node. This exercises the fix on `write_linearized`'s own `Pdf` handle (a
// separate handle from the one `LinearizationPlan::from_pdf` used for planning,
// exactly as the CLI and this file's `flpdf_linearized` helper both do).
// Confirmed (by temporarily reverting the fix) that without it, this fixture
// diverges from qpdf: the interior /Pages node keeps its /Resources dict
// unstripped, the /Page leaf never gains a /Resources key at all (the mutation
// simply never happened on this handle), and the minted object that should
// hold the pushed-down copy resolves to `Object::Null` on this (unpushed)
// handle and ends up dropped from the output entirely — one fewer object than
// qpdf's golden, with every later object number, offset, and hint value
// (`/E`, `/L`) shifted as a result.
#[test]
fn inherited_resources_one_page_byte_identical_to_qpdf() {
    assert_linearize_byte_identical(
        "inherited-resources-one-page.pdf",
        "inherited-resources-one-page",
    );
}

// the pure-SCALAR sibling of the /Resources case above. The /Pages
// node holds a DIRECT /Rotate 90 and the /Page leaf has none, so linearization
// copies the scalar down to the leaf BY VALUE (a literal /Rotate 90) and strips
// it from the now-interior /Pages node — WITHOUT minting a new indirect object,
// unlike the non-scalar /Resources dict which mints a fresh copy. Both share the
// same `push_internal` code path; this pins its copy-by-value arm end-to-end
// (the `scalar_rotate_is_copied_by_value_not_minted` unit test covers only the
// object model, not the serialized bytes). The leaf carries its own /Resources
// so the fixture isolates /Rotate inheritance. Confirmed (by temporarily
// routing the scalar arm through the mint path) that a regression diverges:
// flpdf then writes an extra indirect object and `/Rotate N 0 R` instead of the
// literal, growing the output by 40 bytes and failing this assertion.
#[test]
fn inherited_rotate_one_page_byte_identical_to_qpdf() {
    assert_linearize_byte_identical("inherited-rotate-one-page.pdf", "inherited-rotate-one-page");
}

// A `/Page` leaf shared by two `/Pages` parents that carry different inherited
// `/Rotate` values (A: 90, B: 180). qpdf's `pushInheritedAttributesToPage`
// begins with `(void)cache()`, whose `getAllPagesInternal` clones the 2nd
// occurrence of the shared leaf into a distinct page object (QPDF_pages.cc:202).
// The original leaf then inherits parent A's `/Rotate 90` and the clone inherits
// parent B's `/Rotate 180`; the clone keeps the original leaf's `/Parent` (the
// clone arm never flattens) and both share the `/Contents` stream. The param
// dict must report `/N 2` and the root `/Count` stays 2.
#[test]
fn shared_page_two_parents_byte_identical_to_qpdf() {
    assert_linearize_byte_identical("shared-page-two-parents.pdf", "shared-page-two-parents");
}

// As above, but parent A also carries a DIRECT (non-scalar) `/Resources` that the
// inherited-attribute push mints into a fresh indirect object. This pins the
// relative object numbers of the clone (minted first, in the cache()-equivalent
// pass) and the push-minted `/Resources` (minted after), which must match qpdf's
// cache()-then-push order.
#[test]
fn shared_page_two_parents_pushmint_byte_identical_to_qpdf() {
    assert_linearize_byte_identical(
        "shared-page-two-parents-pushmint.pdf",
        "shared-page-two-parents-pushmint",
    );
}

// The shared-leaf fixture with a damaged startxref, forcing xref reconstruction
// on open. qpdf 11.9.0's getAllPagesInternal has no reconstruction gate
// (QPDF_pages.cc:77-138), so it STILL clones the duplicate leaf into a distinct
// page object; flpdf mirrors this unconditionally (the `!reconstructed` gate was
// removed from the reconstructed-xref path. Pins this path to the qpdf
// 11.9.0 golden.
#[test]
fn shared_page_two_parents_reconstructed_byte_identical_to_qpdf() {
    assert_linearize_byte_identical_repair(
        "shared-page-two-parents-reconstructed.pdf",
        "shared-page-two-parents-reconstructed",
    );
}

/// An interior /Pages node whose /Type is not /Pages and a leaf whose /Type is not
/// /Page. qpdf 11.9.0's getAllPagesInternal overrides both /Type keys
/// (QPDF_pages.cc:89-92, 131-134); the corrected interior node then has its inherited
/// /Rotate pushed down to the leaf, matching qpdf's repair behavior.
#[test]
fn mistyped_page_tree_byte_identical_to_qpdf() {
    assert_linearize_byte_identical("mistyped-page-tree.pdf", "mistyped-page-tree");
}

/// A /Page leaf with no /MediaBox and no ancestor /MediaBox. qpdf 11.9.0's
/// getAllPagesInternal defaults it to letter/ANSI A [0 0 612 792]
/// (QPDF_pages.cc:104-112), matching qpdf's repair behavior.
#[test]
fn missing_mediabox_leaf_byte_identical_to_qpdf() {
    assert_linearize_byte_identical("missing-mediabox-leaf.pdf", "missing-mediabox-leaf");
}

/// A /Page leaf shared by two /Pages parents where ONLY parent A carries a
/// /MediaBox [0 0 200 300]. This pins qpdf 11.9.0's MediaBox-default-BEFORE-clone
/// ordering (QPDF_pages.cc:104-112 runs before the duplicate-clone at :119-130):
/// the shared original is first visited via A (media_box=true, default
/// suppressed), then via B (media_box=false), where the default [0 0 612 792] is
/// applied to the shared ORIGINAL and the clone is then copied from it — so BOTH
/// the A page (the original) and the B page (the clone) end up /MediaBox
/// [0 0 612 792] with /Parent -> A (verified from the qpdf 11.9.0 golden). Were
/// the order reversed (clone before default), the A page would keep A's inherited
/// [0 0 200 300] and only the clone would be [0 0 612 792] — a divergence this
/// guards ( repair 3).
#[test]
fn shared_leaf_mediabox_default_byte_identical_to_qpdf() {
    assert_linearize_byte_identical(
        "shared-leaf-mediabox-default.pdf",
        "shared-leaf-mediabox-default",
    );
}

/// A /Page leaf whose /MediaBox is a direct array with an indirect-reference
/// element ([0 0 612 4 0 R], obj 4 = 792). qpdf 11.9.0's isRectangle()
/// dereferences each element via isNumber(), so the box is a valid rectangle and
/// is kept, NOT overwritten with the [0 0 612 792] default. is_rectangle must
/// resolve each element before defaulting, matching qpdf's repair behavior.
#[test]
fn indirect_mediabox_element_byte_identical_to_qpdf() {
    assert_linearize_byte_identical("indirect-mediabox-element.pdf", "indirect-mediabox-element");
}

/// A /Pages node whose single /Kids entry is a DIRECT (inline) /Page dictionary
/// rather than an indirect reference. qpdf 11.9.0's getAllPagesInternal converts
/// it to an indirect object (QPDF_pages.cc:113-118), matching qpdf's repair behavior.
#[test]
fn direct_leaf_kid_byte_identical_to_qpdf() {
    assert_linearize_byte_identical("direct-leaf-kid.pdf", "direct-leaf-kid");
}

#[test]
fn classic_thumbnail_part9_order_matches_qpdf() {
    let Some(oracle) = pinned_qpdf() else {
        eprintln!("[SKIP cmp_linearize_tests] qpdf 11.9.0 is unavailable");
        return;
    };
    for fixture in [
        "objstm-lin-part9-categories-thumb-74-225.pdf",
        "objstm-lin-part9-pages-shared-thumb-74-225.pdf",
        "objstm-lin-thumbnail-private-shared.pdf",
    ] {
        let input = Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("../../tests/fixtures/compat")
            .join(fixture);
        let directory = tempfile::tempdir().expect("tempdir");
        let expected_path = directory.path().join("qpdf.pdf");
        let status = Command::new(oracle)
            .args(["--linearize", "--deterministic-id", "--warning-exit-0"])
            .arg(&input)
            .arg(&expected_path)
            .status()
            .expect("qpdf runs");
        assert_eq!(status.code(), Some(0), "qpdf linearization must succeed");

        let actual = flpdf_linearized(fixture);
        let expected = std::fs::read(&expected_path).expect("qpdf output");
        if let Some(off) = first_diff(&actual, &expected) {
            panic!(
                "{fixture}: classic thumbnail order differs from qpdf \
                 (flpdf={} bytes, qpdf={} bytes, first diff at byte {off})",
                actual.len(),
                expected.len(),
            );
        }
    }
}

/// A catalog whose /Pages points INTO the page tree (at the first page) instead
/// of at the true root. qpdf 11.9.0's getAllPages walks /Parent up to the real
/// root and rewrites the catalog /Pages (QPDF_pages.cc:50-67), matching qpdf's repair behavior.
#[test]
fn root_pages_points_into_tree_byte_identical_to_qpdf() {
    assert_linearize_byte_identical(
        "root-pages-points-into-tree.pdf",
        "root-pages-points-into-tree",
    );
}

#[test]
fn relinearize_one_page_is_byte_identical_to_qpdf() {
    // Re-linearizing an already-linearized input: the source's old /Linearized
    // param dict and hint stream must be reachability-GC'd, not leaked into the
    // second half, to stay byte-identical to qpdf --linearize.
    assert_linearize_byte_identical("linearized-one-page.pdf", "linearized-one-page");
}

#[test]
fn relinearize_two_page_is_byte_identical_to_qpdf() {
    assert_linearize_byte_identical("linearized-two-page.pdf", "linearized-two-page");
}

#[test]
fn relinearize_two_stream_overflow_source_is_byte_identical_to_qpdf() {
    // qpdf 11.9.0 reads both hint streams from a four-item /H array but only
    // writes a primary stream when re-linearizing. The checked-in source is a
    // tiny hand-authored input with two distinct streams, not a qpdf-writer
    // output; relinearization must garbage-collect both source hint objects.
    assert_linearize_byte_identical(
        "linearized-two-stream-overflow.pdf",
        "linearized-two-stream-overflow",
    );
}

// a live body object (the Catalog) carrying null-resolving indirect
// refs. qpdf drops the null-valued dict keys (/Bad 0 0 R, /Junk 99 0 R, the
// nested /Inner 99 0 R) and inlines `null` for the object-0 array element
// (/ArrZero [0 0 R 2 0 R] -> [null <font>]); flpdf must reproduce that byte for
// byte rather than exit 2 or keep the dead refs.
#[test]
fn dangling_body_refs_classic_byte_identical_to_qpdf() {
    assert_linearize_byte_identical("dangling-body-one-page.pdf", "dangling-body-one-page");
}

// a null-resolving ARRAY ref (/Arr [<null-ref> 8 0 R]) is resurrected
// as an indirect null body object the array points at. The FREE variant (obj 9, a
// free xref row) already worked; the MISSING variant (obj 99, no row) must produce
// the identical layout — qpdf treats the two the same.
#[test]
fn resurrect_free_array_ref_classic_byte_identical_to_qpdf() {
    assert_linearize_byte_identical("resurrect-free-one-page.pdf", "resurrect-free-one-page");
}

#[test]
fn resurrect_missing_array_ref_classic_byte_identical_to_qpdf() {
    assert_linearize_byte_identical(
        "resurrect-missing-one-page.pdf",
        "resurrect-missing-one-page",
    );
}

// a document-level (Catalog) reference to a first-page object marks
// it lc_first_page_shared, so qpdf orders the first-page section private-then-
// shared (Page, Resources, Content, Font) rather than by source number alone.
// Without the document-`others` signal flpdf left the Font in part2 (private)
// and emitted Font before Content (first divergence at byte 353).
#[test]
fn catalog_firstpage_shared_classic_byte_identical_to_qpdf() {
    assert_linearize_byte_identical(
        "catalog-firstpage-shared-one-page.pdf",
        "catalog-firstpage-shared-one-page",
    );
}

//  (non-degenerate shape): two pages share font 6 (other_pages) while
// page 1's private font 7 is referenced by the Catalog /Ref2 (others). Both
// sharing signals land in part6's shared group; qpdf orders the first-page
// section Page, Content, Font6, Font7 (private before shared, shared by source
// number). On `main` this diverges at byte 56; the fix makes it byte-identical.
// (Generate mode for this multi-page shape has a separate, pre-existing ObjStm
// layout divergence, so only the classic layout is pinned here.)
#[test]
fn catalog_firstpage_shared_two_page_classic_byte_identical_to_qpdf() {
    assert_linearize_byte_identical(
        "catalog-firstpage-shared-two-page.pdf",
        "catalog-firstpage-shared-two-page",
    );
}

// a NON-first-page object (page-2 font, obj 7) reached by exactly one
// other page AND by a document-level `others` reference (Catalog /Ref2) is qpdf
// `lc_other` (part9), not `lc_other_page_private` (part7): part7 requires
// others==0 (QPDF_linearization.cc:1128). The demoted object takes a part9 object
// number (after the pages tree) and page 1's part7 `object_count` hint excludes
// it (oracle: page-1 nobjects==2). On `main` flpdf routes it to part7, shifting
// object numbers and the hint; the fix makes it byte-identical. (Generate mode
// for this shape has a separate object-stream layout, so only the classic
// layout is pinned here.)
#[test]
fn catalog_otherpage_other_two_page_classic_is_byte_identical_to_qpdf() {
    assert_linearize_byte_identical(
        "catalog-otherpage-other-two-page.pdf",
        "catalog-otherpage-other-two-page",
    );
}

// the catalog-otherpage-other shape PLUS a real /Info dict (obj 10).
// qpdf treats /Info as an ordinary member of the number-sorted part9 remaining
// lc_other set (QPDF_linearization.cc:1335, `for (auto const& og: lc_other)` over
// a std::set<QPDFObjGen>), so the lower-numbered font (obj 7) precedes /Info: qpdf
// assigns the font new number 4 and /Info new number 5 (golden trailer /Info 5 0 R).
// flpdf previously promoted /Info to a FIXED part9-head slot right after the pages
// tree (before the font), diverging at the trailer /Info N 0 R and every downstream
// offset. The fix drops that promotion so /Info flows through the number-sorted
// remaining lc_other loop. This section covers the classic layout; the generate
// sibling has its own object-stream coverage.
#[test]
fn catalog_otherpage_other_info_two_page_classic_is_byte_identical_to_qpdf() {
    assert_linearize_byte_identical(
        "catalog-otherpage-other-info-two-page.pdf",
        "catalog-otherpage-other-info-two-page",
    );
}

//  (page-tree custom key): a custom extension key on an interior
// /Pages node references the first-page Font. qpdf keeps non-inheritable custom
// keys on /Pages nodes (only the inheritable /Resources,/MediaBox,/CropBox,
// /Rotate are stripped), so ou_root_key("/Pages") still reaches the Font ->
// first-page shared. The Font's source number (2) is below the Content's (5), so
// only the private-before-shared rule yields qpdf's order (Page, Content, Font).
#[test]
fn pages_ext_firstpage_shared_classic_byte_identical_to_qpdf() {
    assert_linearize_byte_identical(
        "pages-ext-firstpage-shared-one-page.pdf",
        "pages-ext-firstpage-shared-one-page",
    );
}

// when the FIRST-PAGE dict directly holds /Arr [<missing-ref> <live-ref>],
// the resurrected null must be classified in the first-page section (Part 2) and
// receive a HIGH object number — not land in part4_rest with a LOW number.
// Oracle: qpdf 11.9.0 assigns obj 9 = null, /Size 10 for this fixture.
#[test]
fn resurrect_missing_page_arr_classic_byte_identical_to_qpdf() {
    assert_linearize_byte_identical(
        "resurrect-missing-page-arr.pdf",
        "resurrect-missing-page-arr",
    );
}

// when Page 1 holds /Bad 99 0 R (dict value → dropped by writer)
// and Page 2 holds /Arr [99 0 R] (array element → resurrected null), the null
// must land in the SECOND-HALF section (low object number) — NOT in Part 2.
// Oracle: qpdf 11.9.0 assigns obj 2 = null in the second-half for this fixture.
#[test]
fn resurrect_page2_arr_page1_dictval_not_in_first_page_section() {
    assert_linearize_byte_identical(
        "resurrect-missing-page1-dictval-page2-arr.pdf",
        "resurrect-missing-page1-dictval-page2-arr",
    );
}

// when Page 1 holds BOTH /Bad 99 0 R (dict value, dropped by
// writer) AND /Good [99 0 R] (array element, resurrected null), the null must
// land in the FIRST-PAGE section — the array edge wins even though the
// dict-value edge is enqueued first (alphabetical key order).
#[test]
fn resurrect_both_edges_same_page_null_in_first_page_section() {
    assert_linearize_byte_identical(
        "resurrect-both-edges-same-page.pdf",
        "resurrect-both-edges-same-page",
    );
}

// cross-object case — Page 1 references resurrectable ref 99 via a
// dict-value edge (/Bad 99 0 R) AND via an array element in a live descendant
// (/Other 4 0 R where obj 4 = << /Good [99 0 R] >>). The dict-value tuple is
// dequeued before the descendant is expanded, but sorting page-dict refs by
// original object number ensures obj 4 (live) is expanded before obj 99
// (resurrectable) is dequeued, so seen_as_array already contains 99 and the
// null is admitted into the first-page section.
#[test]
fn resurrect_crossobj_arr_via_live_desc_null_in_first_page_section() {
    assert_linearize_byte_identical(
        "resurrect-crossobj-arr-via-live-desc.pdf",
        "resurrect-crossobj-arr-via-live-desc",
    );
}

// else-branch ordering — a live non-page object's children must be
// enqueued in ascending original-object-number order, not dict-key (alphabetical)
// order. The fixture has an intermediate dict with /AA→orig6 and /ZZ→orig5;
// alphabetical ordering would emit orig6 before orig5, but qpdf emits orig5
// first (number order).
#[test]
fn else_branch_children_ordered_by_original_object_number() {
    assert_linearize_byte_identical(
        "else-branch-obj-number-order.pdf",
        "else-branch-obj-number-order",
    );
}

// revorder case — resurrectable ref (orig 99) has a LOWER original
// number than the live descendant (orig 100) that holds the array edge
// ([99 0 R]). Sort-at-enqueue puts 99 in the queue before 100 is expanded,
// so seen_as_array is empty when 99 is dequeued → delayed. After the full
// BFS, 100 has populated seen_as_array with 99, so the post-BFS pass admits
// it and inserts it at the correct position in the sorted non-page tail.
#[test]
fn revorder_resurrect_null_in_first_page_section() {
    assert_linearize_byte_identical("revorder-resurrect.pdf", "revorder-resurrect");
}

//  (discriminator): Page leaf at a HIGH original-object-number (10)
// with its content stream at a LOWER original-object-number (3). A naive
// fully-global sort by original number would misplace the Page (renumber it
// higher than its content stream), but qpdf keeps the Page first in its
// closure. flpdf must pin the Page at order[0] and sort only order[1..].
#[test]
fn page_highnum_content_lownum_page_before_content() {
    assert_linearize_byte_identical(
        "page-highnum-content-lownum.pdf",
        "page-highnum-content-lownum",
    );
}

// The resurrectable null (orig 99) is reachable via BOTH
// a Catalog dict-value edge (/OpenAction 99 0 R, dropped by writer) and a
// first-page array edge (/Arr [99 0 R], produces a null body object). Before
// this fix, closure_from_seeds admitted the null-resolving ref into
// open_document_set, causing the null to be misrouted to the open-document
// section (Part 4) with a LOW renumbered number, diverging from qpdf which
// classifies the null as lc_first_page (Part 2, last in the first-page
// section with /O=5, /E=900). The fix skips Object::Null in closure_from_seeds.
#[test]
fn od_null_also_in_first_page_arr_byte_identical_to_qpdf() {
    assert_linearize_byte_identical("od-null-page-arr.pdf", "od-null-page-arr");
}

// The resurrectable null (orig 99) reached via a Catalog
// ARRAY edge (/OpenAction [99 0 R]) — qpdf classifies this as open_document
// (lc_open_document) because the null body IS emitted for the surviving array
// slot.  The null must land in the OD section (pre-/O, before the hint stream)
// not in the first-page section.  The fix tracks array vs dict-value edge type
// in closure_from_seeds via collect_direct_refs_with_context so that
// array-reached xref-absent nulls are admitted to open_document_set while
// dict-value-only nulls are excluded.
#[test]
fn od_catalog_arr_null_byte_identical_to_qpdf() {
    assert_linearize_byte_identical("od-arr-null.pdf", "od-arr-null");
}

// --------------------------------------------------------------------------
// Structural byte-parity: the full-file byte-identity tests
// above now subsume these — flpdf reproduces qpdf's deterministic `/ID[1]` by
// digesting a byte-identical reconstruction of qpdf's *first* write pass (empty
// parameter dict, no hint stream, unresolved first-page xref; see
// `QPDFWriter::writeLinearized` → `computeDeterministicIDData`). These tests are
// kept as a narrower diagnostic: they zero the `/ID[1]` hex run on both sides
// before comparing, so a regression in the structural layout (object numbering,
// physical order, trailers, framing) is isolated from a regression in the
// `/ID[1]` digest, giving a more targeted failure than the strict tests.
// --------------------------------------------------------------------------

/// Replace the 32 hex bytes of every `/ID [<id0><id1>]` array's *second*
/// element with ASCII `'0'`, leaving the permanent identifier `/ID[0]` and all
/// surrounding bytes intact. Used to compare structural layout independently of
/// the deterministic changing identifier.
fn mask_id1(buf: &[u8]) -> Vec<u8> {
    let mut out = buf.to_vec();
    let needle = b" /ID [<";
    let mut i = 0usize;
    while let Some(rel) = find(&out[i..], needle) {
        let arr = i + rel + needle.len();
        // arr -> first hex digit of id0; id0 is 32 hex then '>', then '<', then id1.
        let id0_end = arr + 32;
        // Expect '>' then '<' then 32 id1 hex.
        if id0_end + 2 + 32 <= out.len() && out[id0_end] == b'>' && out[id0_end + 1] == b'<' {
            let id1 = id0_end + 2;
            for b in &mut out[id1..id1 + 32] {
                *b = b'0';
            }
            i = id1 + 32;
        } else {
            i = arr;
        }
    }
    out
}

fn assert_linearize_structurally_byte_identical(fixture: &str, stem: &str) {
    let actual = mask_id1(&flpdf_linearized(fixture));
    let expected = mask_id1(&golden(stem));
    if let Some(off) = first_diff(&actual, &expected) {
        let lo = off.saturating_sub(16);
        panic!(
            "{fixture}: structural layout diverged from qpdf golden (ignoring /ID[1])              (flpdf={} bytes, golden={} bytes, first diff at byte {off})\n             flpdf : {:?}\ngolden: {:?}",
            actual.len(),
            expected.len(),
            &actual[lo..(off + 16).min(actual.len())],
            &expected[lo..(off + 16).min(expected.len())],
        );
    }
}

#[test]
fn one_page_linearized_structurally_byte_identical_to_qpdf() {
    assert_linearize_structurally_byte_identical("one-page.pdf", "one-page");
}

#[test]
fn two_page_linearized_structurally_byte_identical_to_qpdf() {
    assert_linearize_structurally_byte_identical("two-page.pdf", "two-page");
}

#[test]
fn three_page_linearized_structurally_byte_identical_to_qpdf() {
    assert_linearize_structurally_byte_identical("three-page.pdf", "three-page");
}

#[test]
fn lone_flate_l9_linearized_structurally_byte_identical_to_qpdf() {
    // Lone /FlateDecode (level 9) preserved verbatim on the linearized path. The
    // structural comparison includes the stream bytes (only /ID[1] is masked), so
    // it verifies preservation; /ID[1] for a new fixture is a separate divergence.
    assert_linearize_structurally_byte_identical("lone-flate-l9.pdf", "lone-flate-l9");
}

// --------------------------------------------------------------------------
// Body content-stream recompression parity (divergence A).
//
// The linearized writer used to clone each body stream's dict + raw data
// verbatim, preserving e.g. an `[/ASCII85Decode /FlateDecode]` source chain,
// whereas qpdf (and flpdf's plain rewrite) decode the chain and re-encode to a
// single `/FlateDecode`. These tests pin the recompression independently of
// object NUMBERING and physical PLACEMENT (separate divergences), so they pass
// even while the full-file byte-parity tests above are still red.
// --------------------------------------------------------------------------

/// Full-rewrite (non-linearized) one-page.pdf under qpdf-equivalent options:
/// the plain path that already byte-matches `qpdf --static-id`.
fn plain_rewrite_one_page() -> Vec<u8> {
    let path = Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("../../tests/fixtures/compat")
        .join("one-page.pdf");
    let file = std::fs::File::open(&path).unwrap_or_else(|e| panic!("open {path:?}: {e}"));
    let mut pdf = Pdf::open(std::io::BufReader::new(file)).unwrap();

    let opts = WriterTestSettings {
        deterministic_id: true,
        // Same framing the linearized path uses, so the content-stream bytes line up.
        newline_before_endstream: NewlineBeforeEndstream::Never,
        ..WriterTestSettings::default()
    };

    let mut out = Vec::new();
    write_with_settings(&mut pdf, &mut out, &opts).unwrap();
    out
}

mod common;
#[allow(unused_imports)]
use common::{write_linearized_with_settings, write_with_settings, WriterTestSettings};

#[test]
fn encrypted_linearized_v4_aes_state_matches_qpdf() {
    let Some(oracle) = pinned_qpdf() else {
        eprintln!("[SKIP cmp_linearize_tests] qpdf 11.9.0 is unavailable");
        return;
    };
    let fixture = Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("../../tests/fixtures/compat")
        .join("one-page.pdf");
    let directory = tempfile::tempdir().expect("tempdir");
    let qpdf_output = directory.path().join("qpdf-encrypted-linearized.pdf");
    let flpdf_output = directory.path().join("flpdf-encrypted-linearized.pdf");

    let status = Command::new(oracle)
        .args([
            "--linearize",
            "--static-id",
            "--static-aes-iv",
            "--object-streams=disable",
            "--stream-data=uncompress",
            "--encrypt",
            "user",
            "owner",
            "128",
            "--use-aes=y",
            "--",
        ])
        .arg(&fixture)
        .arg(&qpdf_output)
        .status()
        .expect("qpdf writes encrypted linearized output");
    assert_eq!(
        status.code(),
        Some(0),
        "qpdf encryption and linearization succeed"
    );

    let file = std::fs::File::open(&fixture).expect("open one-page fixture");
    let mut pdf = Pdf::open(std::io::BufReader::new(file)).expect("open fixture as PDF");
    let settings = WriterTestSettings {
        static_id: true,
        static_aes_iv: true,
        object_streams: ObjectStreamMode::Disable,
        compress_streams: CompressStreams::No,
        encrypt: Some(EncryptParams::v4_aes128(b"user", b"owner")),
        ..WriterTestSettings::default()
    };
    let actual = write_linearized_with_settings(&mut pdf, &settings)
        .expect("flpdf writes encrypted linearized output");
    std::fs::write(&flpdf_output, &actual).expect("write flpdf output for qpdf check");
    let expected = std::fs::read(&qpdf_output).expect("read qpdf output");
    assert_eq!(
        actual, expected,
        "encrypted linearized output must match qpdf"
    );

    let check_status = Command::new(oracle)
        .args(["--password=user", "--check-linearization"])
        .arg(&flpdf_output)
        .status()
        .expect("qpdf checks the encrypted flpdf output");
    assert_eq!(
        check_status.code(),
        Some(0),
        "qpdf must accept the encrypted flpdf linearization layout"
    );
}

#[test]
fn linearized_extra_header_starts_after_qpdf_separator_newline() {
    let path = Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("../../tests/fixtures/compat")
        .join("one-page.pdf");
    let file = std::fs::File::open(&path).expect("open one-page fixture");
    let mut pdf = Pdf::open(std::io::BufReader::new(file)).expect("open fixture as PDF");
    let settings = WriterTestSettings {
        static_id: true,
        newline_before_endstream: NewlineBeforeEndstream::Never,
        extra_header_text: "%% Comment\n% No newline".to_owned(),
        ..WriterTestSettings::default()
    };

    let output = write_linearized_with_settings(&mut pdf, &settings)
        .expect("write linearized output with extra header");
    let marker = b"%% Comment\n% No newline\n";
    let marker_start = output
        .windows(marker.len())
        .position(|window| window == marker)
        .expect("extra header should be present");
    assert!(marker_start > 0, "extra header must not start at byte zero");
    assert_eq!(
        output[marker_start - 1],
        b'\n',
        "qpdf writes a separator newline before linearized extra header text"
    );
    assert_eq!(
        &output[marker_start + marker.len()..marker_start + marker.len() + 5],
        b"xref\n",
        "qpdf writes xref immediately after extra header's terminating newline"
    );
}

#[test]
fn trailer_external_file_keys_linearized_match_qpdf_11_9() {
    let fixture = "trailer-external-file-keys.pdf";
    let input = Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("../../tests/fixtures/compat")
        .join(fixture);
    let Some(oracle) = pinned_qpdf() else {
        eprintln!("[SKIP cmp_linearize_tests] qpdf 11.9.0 is unavailable");
        return;
    };
    let directory = tempfile::tempdir().expect("tempdir");
    let expected_path = directory.path().join("qpdf.pdf");
    let status = Command::new(oracle)
        .args(["--linearize", "--deterministic-id"])
        .arg(&input)
        .arg(&expected_path)
        .status()
        .expect("qpdf runs");
    assert_eq!(status.code(), Some(0), "qpdf linearization must succeed");

    let actual = flpdf_linearized(fixture);
    let expected = std::fs::read(&expected_path).expect("qpdf output");
    assert_eq!(actual, expected, "linearized trailer keys must match qpdf");
}

/// Extract the page content-stream object body — the single-`/FlateDecode`
/// stream whose dict has neither `/Type` (excludes xref/ObjStm/metadata) nor
/// `/S` (excludes the linearization hint stream) — returning
/// `(dict_bytes, payload_bytes)`. The payload is the `/Length` bytes between
/// the `stream` EOL and `endstream`.
fn content_stream_object(data: &[u8]) -> (Vec<u8>, Vec<u8>) {
    let needle = b"stream\n";
    let mut found: Option<(Vec<u8>, Vec<u8>)> = None;
    let mut i = 0usize;
    while let Some(rel) = find(&data[i..], needle) {
        let stream_kw = i + rel; // position of "stream\n"
                                 // Walk back to the dict opener "<<" on a preceding `N G obj\n` line.
        let dict_open = rfind(&data[..stream_kw], b"<<").expect("stream must follow a dict");
        let dict_close = stream_kw - 1; // the byte before "stream\n" is '\n' after ">>"
        let dict = &data[dict_open..dict_close];
        let payload_start = stream_kw + needle.len();
        let es =
            find(&data[payload_start..], b"endstream").expect("endstream must follow a stream");
        let payload_end = payload_start + es;
        let payload = &data[payload_start..payload_end];
        let is_lone_flate = find(dict, b"/Filter /FlateDecode").is_some();
        let has_type = find(dict, b"/Type").is_some();
        let is_hint = find(dict, b"/S ").is_some();
        if is_lone_flate && !has_type && !is_hint {
            assert!(
                found.is_none(),
                "expected exactly one page content stream in one-page output"
            );
            found = Some((dict.to_vec(), payload.to_vec()));
        }
        i = payload_end + b"endstream".len();
    }
    found.expect("a single-FlateDecode page content stream must be present")
}

fn find(haystack: &[u8], needle: &[u8]) -> Option<usize> {
    haystack.windows(needle.len()).position(|w| w == needle)
}

fn rfind(haystack: &[u8], needle: &[u8]) -> Option<usize> {
    haystack.windows(needle.len()).rposition(|w| w == needle)
}

#[test]
fn one_page_linearized_content_stream_is_recompressed_single_flate() {
    let lin = flpdf_linearized("one-page.pdf");
    let (dict, payload) = content_stream_object(&lin);

    // Recompressed: a single `/FlateDecode`, NOT the source `[/ASCII85Decode
    // /FlateDecode]` chain, and serialized in qpdf's stream-dict key order
    // (`/Length` then a regenerated `/Filter`).
    assert_eq!(
        dict,
        b"<< /Length 82 /Filter /FlateDecode >>",
        "linearized page content stream must be re-encoded to a single \
         /FlateDecode in qpdf key order; got {:?}",
        String::from_utf8_lossy(&dict)
    );
    assert!(
        find(&dict, b"ASCII85").is_none(),
        "the ASCII85 source filter must be dropped on recompression"
    );
    assert_eq!(payload.len(), 82, "/Length must equal the on-disk payload");
}

#[test]
fn one_page_linearized_content_stream_equals_plain_and_qpdf_golden() {
    let lin = flpdf_linearized("one-page.pdf");
    let plain = plain_rewrite_one_page();
    let qpdf = golden("one-page");

    let (lin_dict, lin_payload) = content_stream_object(&lin);
    let (plain_dict, plain_payload) = content_stream_object(&plain);
    let (qpdf_dict, qpdf_payload) = content_stream_object(&qpdf);

    // The recompressed linearized content-stream object must be byte-identical
    // to the plain-path object and to qpdf's golden obj9 — dict AND payload.
    assert_eq!(
        (&lin_dict, &lin_payload),
        (&plain_dict, &plain_payload),
        "linearized content stream must equal the plain-path content stream"
    );
    assert_eq!(
        (&lin_dict, &lin_payload),
        (&qpdf_dict, &qpdf_payload),
        "linearized content stream must equal qpdf golden obj9"
    );
}

// --------------------------------------------------------------------------
// Classic (non-ObjStm) linearize: outline object section routing.
//
// outlines-80-80 (!UseOutlines): catalog /Outlines -> outline dict + 80 items.
// qpdf routes these to part9 (second-half, after /E). Regression: the
// useoutlines case (below) must also stay byte-identical.
//
// useoutlines-80-80 (UseOutlines): /PageMode /UseOutlines causes outline
// objects (dict + 80 items) to route to part6 (first-page section, before /E).
// Their plain bytes count toward page-0 length in the page hint table header.
// --------------------------------------------------------------------------

#[test]
fn outlines_classic_structurally_byte_identical_to_qpdf() {
    assert_classic_structurally_byte_identical(
        "objstm-lin-outlines-80-80.pdf",
        "objstm-lin-outlines-80-80",
    );
}

#[test]
fn outlines_classic_byte_identical_to_qpdf() {
    assert_classic_byte_identical("objstm-lin-outlines-80-80.pdf", "objstm-lin-outlines-80-80");
}

#[test]
fn useoutlines_classic_structurally_byte_identical_to_qpdf() {
    assert_classic_structurally_byte_identical(
        "objstm-lin-useoutlines-80-80.pdf",
        "objstm-lin-useoutlines-80-80",
    );
}

#[test]
fn useoutlines_classic_byte_identical_to_qpdf() {
    assert_classic_byte_identical(
        "objstm-lin-useoutlines-80-80.pdf",
        "objstm-lin-useoutlines-80-80",
    );
}

// useoutlines-shared-page-80-80: the /PageMode /UseOutlines variant of the
// page∩outline overlap fixture below. The shared /S1 font is physically in
// part6 with the outline objects, but qpdf still records page 1's reference
// to it in the Shared Object Hint Table. This is distinct from the ordinary
// UseOutlines fixture above, which has no outline/page overlap.
#[test]
fn useoutlines_shared_page_classic_structurally_byte_identical_to_qpdf() {
    assert_classic_structurally_byte_identical(
        "objstm-lin-useoutlines-shared-page-80-80.pdf",
        "objstm-lin-useoutlines-shared-page-80-80",
    );
}

#[test]
fn useoutlines_shared_page_classic_byte_identical_to_qpdf() {
    assert_classic_byte_identical(
        "objstm-lin-useoutlines-shared-page-80-80.pdf",
        "objstm-lin-useoutlines-shared-page-80-80",
    );
}

// outlines-shared-page-80-80: one font (the highest-numbered outline
// object) is referenced by BOTH pages AND an outline item via /Extra. qpdf's
// categorization (QPDF_linearization.cc:1120) ranks in_outlines above in_first_page,
// so that font is lc_outlines (part9, second half) while the 79 page-only fonts stay
// lc_first_page_shared (part6, first half). The classic path previously kept it in
// the first-page section (param dict 85 vs qpdf 86); this pins the outline >
// first-page precedence on the non-ObjStm path. pushOutlinesToPart emits outlines
// as [root] ++ ascending source number, so the font (max number) is the last object.
#[test]
fn outlines_shared_page_classic_structurally_byte_identical_to_qpdf() {
    assert_classic_structurally_byte_identical(
        "objstm-lin-outlines-shared-page-80-80.pdf",
        "objstm-lin-outlines-shared-page-80-80",
    );
}

#[test]
fn outlines_shared_page_classic_byte_identical_to_qpdf() {
    assert_classic_byte_identical(
        "objstm-lin-outlines-shared-page-80-80.pdf",
        "objstm-lin-outlines-shared-page-80-80",
    );
}

// --------------------------------------------------------------------------
// Open-document closure: objects reachable from the catalog
// open-document keys (/OpenAction, /AcroForm, /PageMode, /Threads,
// /ViewerPreferences) are placed in part4 (first half, before /O) by qpdf in
// ALL object-stream modes. These fixtures carry no source ObjStm, so the
// preserve/disable classic golden pins that partition byte-for-byte.
// --------------------------------------------------------------------------

#[test]
fn od_indirect_length_classic_byte_identical_to_qpdf() {
    assert_classic_byte_identical(
        "objstm-lin-od-indirect-length.pdf",
        "objstm-lin-od-indirect-length",
    );
}

#[test]
fn openaction_classic_byte_identical_to_qpdf() {
    assert_classic_byte_identical(
        "objstm-lin-openaction-80-80.pdf",
        "objstm-lin-openaction-80-80",
    );
}

#[test]
fn acroform_widget_page1_page2_classic_byte_identical_to_qpdf() {
    assert_classic_byte_identical(
        "objstm-lin-acroform-widget-page1-page2.pdf",
        "objstm-lin-acroform-widget-page1-page2",
    );
}

#[test]
fn acroform_widget_page1_only_classic_byte_identical_to_qpdf() {
    assert_classic_byte_identical(
        "objstm-lin-acroform-widget-page1-only.pdf",
        "objstm-lin-acroform-widget-page1-only",
    );
}

#[test]
fn acroform_widget_page0_5_10_classic_byte_identical_to_qpdf() {
    assert_classic_byte_identical(
        "objstm-lin-acroform-widget-page0-5-10.pdf",
        "objstm-lin-acroform-widget-page0-5-10",
    );
}

#[test]
fn acroform_widget_ap_stream_page0_classic_byte_identical_to_qpdf() {
    assert_classic_byte_identical(
        "objstm-lin-acroform-widget-ap-stream-page0.pdf",
        "objstm-lin-acroform-widget-ap-stream-page0",
    );
}

#[test]
fn useoutline_od_shared_stream_classic_byte_identical_to_qpdf() {
    assert_classic_byte_identical(
        "objstm-lin-useoutline-od-shared-stream.pdf",
        "objstm-lin-useoutline-od-shared-stream",
    );
}

#[test]
fn od_indirect_length_flate_classic_byte_identical_to_qpdf() {
    assert_classic_byte_identical(
        "objstm-lin-od-indirect-length-flate.pdf",
        "objstm-lin-od-indirect-length-flate",
    );
}

/// Exercises the `part4_open_document_plain` source-number sort with MORE THAN
/// ONE open-document object (multiple /OpenAction destinations), so the ordering
/// is pinned against the qpdf oracle rather than only reasoned about.
#[test]
fn openaction_multi_od_classic_byte_identical_to_qpdf() {
    assert_classic_byte_identical(
        "objstm-lin-openaction-multi-od.pdf",
        "objstm-lin-openaction-multi-od",
    );
}

#[test]
fn outline_od_shared_stream_classic_byte_identical_to_qpdf() {
    assert_classic_byte_identical(
        "objstm-lin-outline-od-shared-stream.pdf",
        "objstm-lin-outline-od-shared-stream",
    );
}