The local build pipeline

The project is organized around one local, reproducible flow.

official release or local DocBook XML
    -> edition resolution and source manifest
        -> generic DocBook structure parsing
            -> part-specific semantic parsers
                -> canonical intermediate records
                    -> transactional SQLite import
                        -> deterministic resolver layer
                            -> CLI, Python, and MCP adapters

1. Acquisition

The source layer can:

• discover the concrete current edition;
• validate a historical edition against the official archive;
• download selected parts and formats;
• recursively mirror a selected CHTML part tree;
• register local DocBook XML;
• compute artifact digests;
• write an immutable manifest.

Network access belongs to acquisition. Query surfaces operate on the local database.

2. Generic DocBook parsing

The generic parser preserves document structure needed across parts:

• sections and anchors;
• tables and rows;
• variable lists;
• cross-references;
• text suitable for bounded retrieval and full-text search;
• parser warnings and source references.

This structural layer supports both specialized semantic parsing and cited text fallback.

3. Part-specific parsing

Specialized parsers identify semantic structures such as:

• PS3.3 IODs, modules, macros, attribute uses, and includes;
• PS3.4 SOP Classes;
• PS3.5 VR definitions and encoding facts;
• PS3.6 data elements and UIDs;
• selected PS3.7 and PS3.8 behavior structures;
• PS3.10 file-meta and media records;
• PS3.16 templates, context groups, and codes;
• PS3.18 transactions and media records.

A parser can emit warnings instead of silently discarding an uncertain structure.

4. Canonical records

The intermediate representation separates parsing from storage. Records carry edition and source-reference information so a database row does not lose its origin.

Relationships such as module includes and SOP-Class-to-IOD links are imported as graph edges rather than flattened prose.

5. Transactional SQLite import

The builder applies schema migrations, imports manifest and document structure, imports semantic records, and writes build metadata.

A failed build does not intentionally publish a partially accepted result as a successful database. An existing target is protected unless --force is explicit.

6. Resolver layer

Resolvers combine repositories, identifier validation, graph traversal, condition handling, citation construction, and the shared response contract.

They handle normal uncertainty with structured statuses, candidates, warnings, and null fields rather than free-form exceptions or guesses.

7. Thin public adapters

• CLI serializes a ToolResponse to formatted JSON.
• Python returns the typed ToolResponse.
• MCP registers typed tool functions, opens SQLite read-only, and serializes the same response.

This keeps behavior consistent across interfaces and makes tool traces comparable in agent evaluations.

Quality feedback loops

The pipeline emits build metrics and supports threshold gates for unresolved includes, unresolved cross-references, and parser warnings. Verification later checks source and database provenance.

These controls make parser limitations visible without pretending that a zero warning count proves complete DICOM conformance.