feat: parse PDB files into canonical intermediate representation

[AshGreyG]

Parent Issue

Part of #11.

Problem

Chitin needs a reliable ingestion layer for Protein Data Bank (.pdb) files before the 3D structure viewer can construct renderable scenes. Raw PDB records should not flow directly into rendering code, because fixed-column parsing, alternate locations, model boundaries, insertion codes, occupancy values, element inference, and malformed-record handling require format-specific logic that should remain isolated from downstream consumers.

Proposal

Implement a parser for standard PDB files that converts raw structural records into a canonical internal intermediate representation (IR). The IR will serve as the authoritative in-memory data source for downstream representation generation, scene construction, selection, analysis, and rendering pipelines.

The parser and IR must remain independent of GPUI and wgpu. Rendering crates should consume the IR or derived representation data rather than parse PDB text directly.

Scope

The initial parser should support the structural records needed to reconstruct ordinary macromolecular coordinate models, including:

• ATOM and HETATM coordinate records.
• MODEL and ENDMDL boundaries for multi-model structures.
• TER chain termination records.
• CONECT records where explicit connectivity is present.
• Atom serial numbers, atom names, alternate-location identifiers, residue names, chain identifiers, residue sequence numbers, insertion codes, Cartesian coordinates, occupancy, temperature factors, element symbols, and formal charges.
• Clear distinction between polymer atoms, hetero atoms, and waters where the input permits it.
• Preservation of source identifiers required for diagnostics and round-tripping decisions.
• Recoverable diagnostics for unsupported or malformed records, without panicking on untrusted files.

Header metadata outside the structural ingestion path may be deferred unless it is required to interpret coordinates correctly.

IR Requirements

The resulting IR should be memory-efficient, type-safe, and stable enough to become the canonical structure model consumed by later pipeline stages. The design should:

• Use typed identifiers or indices for models, chains, residues, atoms, and bonds instead of passing raw array indices across crate boundaries.
• Store repeated strings and categorical values efficiently, avoiding unnecessary per-atom heap allocations.
• Preserve hierarchy from structure to model, chain, residue, and atom while still allowing efficient contiguous iteration over atoms.
• Represent optional PDB fields explicitly rather than relying on sentinel values.
• Separate parsed source data from renderer-specific meshes, colors, GPU buffers, and camera state.
• Document ownership, indexing invariants, alternate-location policy, connectivity policy, and error semantics.

Out of Scope

• mmCIF parsing, which should be implemented as a separate frontend targeting the same canonical IR.
• Cartoon, ribbon, surface, stick, or ball-and-stick mesh generation.
• GPU resource creation or GPUI panel integration.
• Full validation against every historical or non-standard PDB extension.
• Editing and serialization back to PDB in the initial implementation.

Acceptance Criteria

• A public parser API accepts PDB text or bytes and returns the canonical structure IR plus structured diagnostics or a typed error.
• Representative single-model and multi-model PDB fixtures are parsed into the expected model, chain, residue, atom, and bond hierarchy.
• ATOM, HETATM, MODEL, ENDMDL, TER, and supported CONECT records are covered by tests.
• Alternate locations, insertion codes, negative residue numbers, missing optional fields, waters, ligands, and malformed fixed-width records have explicit tested behavior.
• The implementation does not panic on malformed user input.
• Domain parsing and IR crates do not depend on GPUI or wgpu.
• Downstream code can iterate atoms contiguously and resolve model, chain, residue, and atom identities through typed handles or equivalent type-safe indices.
• Benchmarks or measurements document parse time and memory use for at least one typical protein and one large structure fixture.
• Parser behavior is checked against a small corpus of real PDB files and documented where unsupported records are intentionally ignored.

Validation

Suggested validation commands should include focused unit tests, corpus tests, malformed-input tests, and parser benchmarks once the crate layout is established.