codendium 1.0.0__py3-none-any.whl

copyright_deposit/assets/fonts/README.md

@@ -0,0 +1,31 @@
+# Optional deposit font
+
+Codendium renders deposits in **Courier** by default. Courier is one of the PDF
+base-14 faces, so it needs no embedding, is guaranteed monospaced, renders
+identically in every viewer, and raises no font-redistribution question — which
+is what you want in a document you are filing.
+
+To use a different face, drop a monospaced TrueType file into this directory.
+The first non-bold, non-italic `.ttf` here is picked up automatically
+(`core.metrics._bundled_font`), embedded in the PDF, and used instead of
+Courier. A `Foo-Bold.ttf` or `FooBd.ttf` beside `Foo.ttf` is used for the bold
+banner lines.
+
+You can also point at a font per build without copying anything here:
+
+```
+py -m copyright_deposit build <folder> --font "C:/path/to/DejaVuSansMono.ttf"
+```
+
+Two rules the tool enforces whichever font you choose:
+
+- **It must be monospaced.** The page grid, the column count and therefore the
+  page estimate all assume a fixed advance width. A proportional font is
+  rejected at load time and Courier is used instead.
+- **Missing glyphs are replaced, never dropped.** Characters the font cannot
+  draw become `?` and the count is reported as a build warning, so nothing
+  disappears from the deposit silently.
+
+No font is committed here. Check the licence of any font you add — some
+disallow embedding or redistribution, and this directory ships inside the
+Python package.

copyright_deposit/assets/logo.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256" role="img" aria-label="Codendium">
+  <title>Codendium</title>
+  <!--
+    Bracket monogram: a copyright mark held inside code brackets.
+
+    Deliberately monochrome in a single mid-blue. A two-tone mark with a
+    dark glyph would vanish on GitHub's dark theme, and a light one would
+    wash out on the light theme; this hue clears both, and at 16px the
+    bracket-and-circle silhouette still reads.
+
+    The (c) is drawn as a stroked circle plus an arc - never a <text>
+    glyph, which would depend on fonts the viewer may not have.
+  -->
+  <g fill="none" stroke="#2F6FEB" stroke-linecap="square" stroke-linejoin="miter">
+    <!-- left bracket -->
+    <path d="M 78 46 L 44 46 L 44 210 L 78 210" stroke-width="22"/>
+    <!-- right bracket -->
+    <path d="M 178 46 L 212 46 L 212 210 L 178 210" stroke-width="22"/>
+    <!-- Copyright ring. Sized to leave clear air between it and the
+         brackets: at 16px the C inside is never going to be legible, so
+         what has to survive is three distinct shapes rather than a blob. -->
+    <circle cx="128" cy="128" r="41" stroke-width="14"/>
+    <!-- the C inside, opening to the right -->
+    <path d="M 139.3 114.6 A 17.5 17.5 0 1 0 139.3 141.4" stroke-width="11" stroke-linecap="round"/>
+  </g>
+</svg>

copyright_deposit/cli.py

@@ -0,0 +1,314 @@
+"""Headless entry point.
+
+Everything the GUI can do is available here, which keeps the pipeline
+testable without Qt and makes builds reproducible from a script or CI.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import BuildSettings
+from .core import lineranges, ordering
+from .core.deposit import MODE_ENTIRE
+from .core.discovery import git_revision
+from .core.pipeline import Pipeline
+
+
+def _add_common(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("root", help="folder containing the source code")
+    parser.add_argument("-o", "--output", default="out", help="output folder (default: out)")
+    parser.add_argument("--basename", default="deposit", help="output file prefix")
+    parser.add_argument("--order-file", help="text file listing the deposit order, one path per line")
+    parser.add_argument("--settings", help="load a saved settings JSON file")
+
+    ident = parser.add_argument_group("identification block")
+    ident.add_argument("--name", help="program name")
+    ident.add_argument("--program-version", help="program version, e.g. 1.0.0")
+    ident.add_argument("--owner", help="copyright owner")
+    ident.add_argument("--year", help="copyright year")
+    ident.add_argument("--date", help="release/build date (YYYY-MM-DD)")
+    ident.add_argument("--revision", help="source revision; use 'auto' to read git HEAD")
+
+    policy = parser.add_argument_group("comment policy")
+    policy.add_argument("--keep-comments", action="store_true", help="do not strip comments")
+    policy.add_argument("--keep-docstrings", action="store_true", help="do not strip docstrings")
+    policy.add_argument(
+        "--preserve-legal-headers",
+        action="store_true",
+        help="keep leading comment blocks that carry a copyright or licence notice",
+    )
+    policy.add_argument("--no-collapse-blanks", action="store_true", help="keep blank-line runs")
+
+    page = parser.add_argument_group("page grid")
+    page.add_argument("--page-size", choices=["letter", "a4"], help="default: letter")
+    page.add_argument("--font-size", type=float, help="default: 9.5")
+    page.add_argument("--lines-per-page", type=int, help="default: 40")
+    page.add_argument("--line-numbers", action="store_true", help="show original source line numbers")
+    page.add_argument("--font", help="'Courier' or a path to a monospaced .ttf")
+
+    other = parser.add_argument_group("other")
+    other.add_argument("--exclude", action="append", default=[], help="relative path to exclude (repeatable)")
+    other.add_argument(
+        "--lines",
+        action="append",
+        default=[],
+        metavar="PATH=RANGES",
+        help="deposit only part of a file, e.g. --lines src/core.py=1-50,120-200 (repeatable)",
+    )
+    other.add_argument("--no-unlisted", action="store_true", help="include only files named in the order list")
+    other.add_argument("--redact", action="store_true", help="enable trade-secret redaction")
+    other.add_argument("--redact-regex", action="append", default=[], help="redaction pattern (repeatable)")
+    other.add_argument("--no-scan", action="store_true", help="skip the secret and third-party scans")
+
+
+def _settings_from_args(args: argparse.Namespace) -> BuildSettings:
+    if getattr(args, "settings", None):
+        settings = BuildSettings.from_json(Path(args.settings).read_text(encoding="utf-8"))
+    else:
+        settings = BuildSettings()
+
+    settings.source_root = str(Path(args.root).resolve())
+    settings.output_dir = str(Path(args.output).resolve())
+    settings.output_basename = args.basename
+
+    if args.order_file:
+        settings.order_entries = ordering.parse_order_text(
+            Path(args.order_file).read_text(encoding="utf-8")
+        )
+
+    header = settings.header
+    if args.name:
+        header.program_name = args.name
+    if args.program_version:
+        header.version = args.program_version
+    if args.owner:
+        header.copyright_owner = args.owner
+    if args.year:
+        header.copyright_year = args.year
+    if args.date:
+        header.release_date = args.date
+    if args.revision:
+        header.revision = git_revision(settings.source_root) if args.revision == "auto" else args.revision
+
+    transform = settings.transform
+    if args.keep_comments:
+        transform.strip_comments = False
+    if args.keep_docstrings:
+        transform.strip_docstrings = False
+    if args.preserve_legal_headers:
+        transform.preserve_legal_headers = True
+    if args.no_collapse_blanks:
+        transform.collapse_blank_runs = False
+
+    layout = settings.layout
+    if args.page_size:
+        layout.page_size = args.page_size
+    if args.font_size:
+        layout.font_size = args.font_size
+    if args.lines_per_page:
+        layout.lines_per_page = args.lines_per_page
+    if args.line_numbers:
+        layout.show_line_numbers = True
+    if args.font:
+        layout.font_name = args.font
+
+    settings.excluded = list(args.exclude)
+    settings.include_unlisted = not args.no_unlisted
+
+    for entry in args.lines:
+        path, separator, spec = entry.partition("=")
+        if not separator:
+            raise SystemExit(f"error: --lines expects PATH=RANGES, got '{entry}'")
+        path = path.strip().replace("\\", "/").lstrip("./")
+        error = lineranges.validate(spec)
+        if error:
+            raise SystemExit(f"error: --lines {path}: {error}")
+        settings.line_ranges[path] = spec.strip()
+    if args.redact or args.redact_regex:
+        settings.redaction.enabled = True
+        settings.redaction.regexes.extend(args.redact_regex)
+    if args.no_scan:
+        settings.scan.scan_secrets = False
+        settings.scan.scan_third_party = False
+
+    return settings
+
+
+def _progress(stage: str, current: int, total: int) -> None:
+    if total <= 1:
+        sys.stderr.write(f"\r{stage}...")
+    else:
+        sys.stderr.write(f"\r{stage}: {current}/{total}   ")
+    sys.stderr.flush()
+
+
+def _report(estimate, show_what_if: list | None = None) -> None:
+    selection = estimate.selection
+    print()
+    print(f"Files included    : {len(estimate.prepared)}")
+    print(f"Page grid         : {estimate.geometry_note}")
+    print(f"Complete program  : {estimate.page_count} page(s)")
+    if selection.mode == MODE_ENTIRE:
+        print("Deposit rule      : 50 pages or fewer - the entire program is deposited")
+    else:
+        first, last = selection.omitted or (0, 0)
+        print(
+            f"Deposit rule      : over 50 pages - first {estimate.settings.deposit.head_pages} "
+            f"and last {estimate.settings.deposit.tail_pages} pages "
+            f"(pages {first}-{last} omitted)"
+        )
+    print(f"Pages deposited   : {selection.deposited_pages}")
+
+    omitted_files = estimate.omitted_files()
+    if omitted_files:
+        print(f"\nFiles the Office will not see ({len(omitted_files)}):")
+        for path in omitted_files[:10]:
+            print(f"  - {path}")
+        if len(omitted_files) > 10:
+            print(f"  ... and {len(omitted_files) - 10} more")
+
+    if show_what_if:
+        print("\nPage count by comment policy:")
+        for label, pages, mode in show_what_if:
+            print(f"  {label:<30} {pages:>5} pages  ({mode})")
+
+    secrets = estimate.scan.sorted_secrets()
+    if secrets:
+        print(f"\nSecret/PII findings ({len(secrets)}):")
+        for finding in secrets[:10]:
+            print(f"  [{finding.severity:>6}] {finding.location()} - {finding.detail} ({finding.excerpt})")
+        if len(secrets) > 10:
+            print(f"  ... and {len(secrets) - 10} more")
+
+    third_party = estimate.scan.sorted_third_party()
+    if third_party:
+        print(f"\nThird-party indicators ({len(third_party)}):")
+        for finding in third_party[:10]:
+            print(f"  [{finding.severity:>6}] {finding.location()} - {finding.detail}")
+        if len(third_party) > 10:
+            print(f"  ... and {len(third_party) - 10} more")
+
+    if estimate.warnings:
+        print(f"\nWarnings ({len(estimate.warnings)}):")
+        for warning in estimate.warnings[:15]:
+            print(f"  - {warning}")
+        if len(estimate.warnings) > 15:
+            print(f"  ... and {len(estimate.warnings) - 15} more")
+
+
+def cmd_estimate(args: argparse.Namespace) -> int:
+    settings = _settings_from_args(args)
+    pipeline = Pipeline()
+    estimate = pipeline.estimate(settings, progress=_progress)
+    what_if = pipeline.what_if(settings, progress=_progress) if args.what_if else None
+    _report(estimate, what_if)
+    return 0
+
+
+def cmd_build(args: argparse.Namespace) -> int:
+    settings = _settings_from_args(args)
+    pipeline = Pipeline()
+    result = pipeline.build(settings, progress=_progress, force=args.force)
+    _report(result.estimate)
+
+    if result.blocked_by:
+        print("\nBUILD BLOCKED: possible credentials found in the selected files.")
+        for finding in result.blocked_by:
+            print(f"  {finding.location()} - {finding.detail} ({finding.excerpt})")
+        print("\nRemove them, redact them with --redact, or re-run with --force.")
+        return 2
+
+    print("\nWritten:")
+    for path in result.outputs:
+        print(f"  {path}")
+    if result.manifest_path:
+        print(f"  {result.manifest_path}")
+        print(f"  {result.summary_path}")
+    print(f"\nStatement for the application:\n  {result.estimate.selection.filing_statement()}")
+    return 0
+
+
+def cmd_suggest_order(args: argparse.Namespace) -> int:
+    settings = _settings_from_args(args)
+    pipeline = Pipeline()
+    found = pipeline.discover(settings)
+    suggested = ordering.suggest_order(found.files)
+    text = ordering.format_order_text(suggested)
+    if args.write:
+        Path(args.write).write_text(text, encoding="utf-8")
+        print(f"Wrote {len(suggested)} entries to {args.write}")
+    else:
+        sys.stdout.write(text)
+    return 0
+
+
+def cmd_save_settings(args: argparse.Namespace) -> int:
+    settings = _settings_from_args(args)
+    Path(args.write).write_text(settings.to_json(), encoding="utf-8")
+    print(f"Wrote settings to {args.write}")
+    return 0
+
+
+def _prog_name() -> str:
+    """Name this invocation by the command the user actually typed.
+
+    The same parser is reached through three entry points - ``codendium``,
+    ``copyright-deposit`` and ``python -m copyright_deposit`` - so a hardcoded
+    prog would print a command the reader did not run.
+    """
+    stem = Path(sys.argv[0]).stem
+    if stem in {"__main__", "-m", ""}:
+        return "python -m copyright_deposit"
+    return stem
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=_prog_name(),
+        description="Build US Copyright Office compliant source-code deposit PDFs.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    estimate = sub.add_parser("estimate", help="report the page count without rendering a PDF")
+    _add_common(estimate)
+    estimate.add_argument("--what-if", action="store_true", help="compare page counts across comment policies")
+    estimate.set_defaults(func=cmd_estimate)
+
+    build = sub.add_parser("build", help="render the deposit PDFs")
+    _add_common(build)
+    build.add_argument("--force", action="store_true", help="build even if credentials were found")
+    build.set_defaults(func=cmd_build)
+
+    suggest = sub.add_parser("suggest-order", help="propose a deposit order from the code structure")
+    _add_common(suggest)
+    suggest.add_argument("--write", help="write the order list to this file")
+    suggest.set_defaults(func=cmd_suggest_order)
+
+    save = sub.add_parser("save-settings", help="write the resolved settings to JSON")
+    _add_common(save)
+    save.add_argument("--write", required=True, help="destination JSON file")
+    save.set_defaults(func=cmd_save_settings)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except KeyboardInterrupt:
+        print("\nInterrupted.", file=sys.stderr)
+        return 130
+    except FileNotFoundError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

copyright_deposit/config.py

@@ -0,0 +1,269 @@
+"""Settings model.
+
+Every knob the tool exposes lives here as a dataclass. The whole tree is
+JSON round-trippable, so a build can be stored in history and reproduced
+byte-for-byte later.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import json
+from dataclasses import dataclass, field
+from datetime import date
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Defaults
+# ---------------------------------------------------------------------------
+
+DEFAULT_EXTENSIONS: tuple[str, ...] = (
+    ".py", ".pyi", ".pyx",
+    ".c", ".h", ".cpp", ".cc", ".cxx", ".hpp", ".hh", ".hxx", ".inl",
+    ".java", ".cs", ".js", ".jsx", ".ts", ".tsx", ".go", ".rs", ".swift",
+    ".kt", ".kts", ".m", ".mm", ".scala", ".php", ".rb", ".pl", ".lua",
+    ".sql", ".sh", ".bash", ".ps1", ".r", ".jl", ".dart", ".vb", ".f90",
+)
+
+# Directory names never worth depositing: build output, dependencies,
+# tool caches and vendored third-party code.
+DEFAULT_IGNORE_DIRS: tuple[str, ...] = (
+    ".git", ".hg", ".svn", ".idea", ".vs", ".vscode", "__pycache__",
+    ".pytest_cache", ".mypy_cache", ".ruff_cache", ".tox", ".eggs",
+    "node_modules", "bower_components", "venv", ".venv", "env",
+    "site-packages", "dist-packages", "vendor", "third_party", "thirdparty",
+    "external", "extern", "build", "_build", "dist", "out", "bin", "obj",
+    "target", "cmake-build-debug", "cmake-build-release", "coverage",
+    "htmlcov", ".next", ".nuxt", ".gradle", "Pods", "DerivedData",
+)
+
+DEFAULT_IGNORE_GLOBS: tuple[str, ...] = (
+    "*.min.js", "*.min.css", "*_pb2.py", "*_pb2_grpc.py", "*.pb.go",
+    "*.pb.cc", "*.pb.h", "*.g.cs", "*.designer.cs", "*.generated.*",
+    "*.lock", "package-lock.json",
+)
+
+LEGAL_HEADER_PATTERN = (
+    r"copyright|\(c\)|©|licen[sc]e|SPDX-License-Identifier|all rights reserved"
+)
+
+MAX_FILE_BYTES = 2 * 1024 * 1024
+MINIFIED_MEAN_LINE_LEN = 200
+
+# Compendium section 721.6.
+DEPOSIT_PAGE_THRESHOLD = 50
+DEPOSIT_HEAD_PAGES = 25
+DEPOSIT_TAIL_PAGES = 25
+
+# Compendium section 721.7: blocked-out material may not exceed this share.
+MAX_REDACTION_RATIO = 0.49
+
+
+# ---------------------------------------------------------------------------
+# Dataclasses
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class HeaderInfo:
+    """The identification block the Office requires on the first page."""
+
+    program_name: str = ""
+    version: str = "1.0.0"
+    release_date: str = field(default_factory=lambda: date.today().isoformat())
+    revision: str = ""  # git short hash; optional but pins the exact deposit
+    copyright_owner: str = ""
+    copyright_year: str = field(default_factory=lambda: str(date.today().year))
+    deposit_label: str = "Deposit Copy - Identifying Portions of Source Code"
+    extra_notice: str = ""
+
+    def lines(self) -> list[str]:
+        """Render the block exactly as it appears at the top of page 1."""
+        out = [self.program_name.strip() or "[PROGRAM NAME]"]
+        out.append(f"Version: {self.version}".rstrip())
+        if self.release_date:
+            out.append(f"Release/build date: {self.release_date}")
+        if self.revision:
+            out.append(f"Source revision/commit: {self.revision}")
+        owner = self.copyright_owner.strip() or "[copyright owner]"
+        out.append(f"Copyright (c) {self.copyright_year} {owner}")
+        if self.deposit_label:
+            out.append(self.deposit_label)
+        if self.extra_notice:
+            out.extend(self.extra_notice.splitlines())
+        return out
+
+    def title_line(self) -> str:
+        name = self.program_name.strip() or "[PROGRAM NAME]"
+        return f"{name} v{self.version}" if self.version else name
+
+
+@dataclass
+class DiscoveryOptions:
+    extensions: list[str] = field(default_factory=lambda: list(DEFAULT_EXTENSIONS))
+    ignore_dirs: list[str] = field(default_factory=lambda: list(DEFAULT_IGNORE_DIRS))
+    ignore_globs: list[str] = field(default_factory=lambda: list(DEFAULT_IGNORE_GLOBS))
+    respect_gitignore: bool = True
+    max_file_bytes: int = MAX_FILE_BYTES
+    skip_minified: bool = True
+    skip_empty: bool = True
+    follow_symlinks: bool = False
+
+
+@dataclass
+class TransformOptions:
+    """Comment/whitespace policy. Default is 'strip everything'."""
+
+    strip_comments: bool = True
+    strip_docstrings: bool = True
+    preserve_legal_headers: bool = False
+    preserve_shebang: bool = True
+    collapse_blank_runs: bool = True
+    max_blank_run: int = 1
+    trim_trailing_whitespace: bool = True
+    expand_tabs: bool = True
+    tab_width: int = 4
+
+    def cache_key(self) -> str:
+        return json.dumps(dataclasses.asdict(self), sort_keys=True)
+
+
+@dataclass
+class LayoutOptions:
+    page_size: str = "letter"  # "letter" | "a4"
+    font_name: str = "Courier"  # base-14; or a .ttf path / bundled family name
+    font_size: float = 9.5
+    lines_per_page: int = 40
+    margin: float = 54.0  # 0.75 inch
+    show_line_numbers: bool = False
+    show_file_banners: bool = True
+    running_header: bool = True
+    page_numbers: bool = True
+    wrap_marker: str = ">> "
+    file_gap_lines: int = 1  # blank lines before a file banner
+    start_files_on_new_page: bool = False
+
+    def cache_key(self) -> str:
+        return json.dumps(dataclasses.asdict(self), sort_keys=True)
+
+
+@dataclass
+class RedactionRules:
+    """Compendium 721.7 blocked-out material."""
+
+    enabled: bool = False
+    begin_marker: str = "COPYRIGHT-REDACT-BEGIN"
+    end_marker: str = "COPYRIGHT-REDACT-END"
+    regexes: list[str] = field(default_factory=list)
+    # "relative/path.py:12" entries, typically queued from the secret scanner.
+    manual_lines: list[str] = field(default_factory=list)
+
+    def cache_key(self) -> str:
+        return json.dumps(dataclasses.asdict(self), sort_keys=True)
+
+
+@dataclass
+class ScanOptions:
+    scan_secrets: bool = True
+    scan_third_party: bool = True
+    block_on_secrets: bool = True
+    ignored_findings: list[str] = field(default_factory=list)  # finding ids
+
+
+@dataclass
+class DepositOptions:
+    apply_rule: bool = True
+    threshold: int = DEPOSIT_PAGE_THRESHOLD
+    head_pages: int = DEPOSIT_HEAD_PAGES
+    tail_pages: int = DEPOSIT_TAIL_PAGES
+    separator_page: bool = True
+    keep_original_page_numbers: bool = True
+
+
+@dataclass
+class BuildSettings:
+    source_root: str = ""
+    output_dir: str = ""
+    output_basename: str = "deposit"
+    order_entries: list[str] = field(default_factory=list)
+    excluded: list[str] = field(default_factory=list)  # relative paths
+    # Optional per-file line selection: {"src/core.py": "1-50, 120-200"}.
+    # An absent or empty entry means the whole file.
+    line_ranges: dict[str, str] = field(default_factory=dict)
+    include_unlisted: bool = True
+    write_full_pdf: bool = True
+    write_deposit_pdf: bool = True
+    write_manifest: bool = True
+
+    header: HeaderInfo = field(default_factory=HeaderInfo)
+    discovery: DiscoveryOptions = field(default_factory=DiscoveryOptions)
+    transform: TransformOptions = field(default_factory=TransformOptions)
+    layout: LayoutOptions = field(default_factory=LayoutOptions)
+    redaction: RedactionRules = field(default_factory=RedactionRules)
+    scan: ScanOptions = field(default_factory=ScanOptions)
+    deposit: DepositOptions = field(default_factory=DepositOptions)
+
+    # -- serialisation ----------------------------------------------------
+
+    def to_dict(self) -> dict[str, Any]:
+        return dataclasses.asdict(self)
+
+    def to_json(self, indent: int | None = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, sort_keys=True)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "BuildSettings":
+        return _rebuild(cls, data)
+
+    @classmethod
+    def from_json(cls, text: str) -> "BuildSettings":
+        return cls.from_dict(json.loads(text))
+
+    def fingerprint(self) -> str:
+        """Stable hash of every setting; identifies a run in the history."""
+        return hashlib.sha256(self.to_json(indent=None).encode("utf-8")).hexdigest()
+
+    def content_fingerprint(self) -> str:
+        """Hash of only the settings that affect the rendered pages.
+
+        Where the PDF is written, and which artifacts are produced, do not
+        change a single glyph - so they must not change the fingerprint
+        stamped into the file. Excluding them is what makes two runs of the
+        same source byte-identical regardless of output folder.
+        """
+        data = self.to_dict()
+        for key in ("output_dir", "output_basename", "write_full_pdf",
+                    "write_deposit_pdf", "write_manifest"):
+            data.pop(key, None)
+        payload = json.dumps(data, sort_keys=True)
+        return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+_NESTED: dict[str, type] = {
+    "header": HeaderInfo,
+    "discovery": DiscoveryOptions,
+    "transform": TransformOptions,
+    "layout": LayoutOptions,
+    "redaction": RedactionRules,
+    "scan": ScanOptions,
+    "deposit": DepositOptions,
+}
+
+
+def _rebuild(cls: type, data: Any) -> Any:
+    """Rebuild nested dataclasses, tolerating unknown or missing keys.
+
+    Tolerance matters: history rows written by an older version of the tool
+    must still load rather than crash the GUI.
+    """
+    if not isinstance(data, dict):
+        return data
+    kwargs: dict[str, Any] = {}
+    known = {f.name for f in dataclasses.fields(cls)}
+    for key, value in data.items():
+        if key not in known:
+            continue
+        nested = _NESTED.get(key)
+        kwargs[key] = _rebuild(nested, value) if nested is not None else value
+    return cls(**kwargs)

copyright_deposit/core/__init__.py

@@ -0,0 +1 @@
+"""Core pipeline: discovery -> ordering -> transform -> layout -> render."""