Cache and source manifests

The default local cache root is:

~/.cache/dicom-standard-kb

Override it with --cache-dir, DICOM_KB_CACHE_DIR, or profile artifact_dir.

Default layout

~/.cache/dicom-standard-kb/
  artifacts/
    <edition>/
      manifest.json
      raw/
        source/
          docbook/
            part03/
              part03.xml
            ...
        pdf/
          part03.pdf
        html/
          part03.html
        chtml/
          part03/
            PS3.3.html
        targetdb/
          PS3_03_target.db
  db/
    <edition>.sqlite

Only requested formats and parts exist. A full CHTML mirror adds the discovered files under the part’s CHTML directory.

Source artifact destinations

For part number NN:

Format	Cache-relative destination
docbook_xml	artifacts/<edition>/raw/source/docbook/partNN/partNN.xml
pdf	artifacts/<edition>/raw/pdf/partNN.pdf
html	artifacts/<edition>/raw/html/partNN.html
chtml	artifacts/<edition>/raw/chtml/partNN/PS3.N.html
targetdb	artifacts/<edition>/raw/targetdb/PS3_NN_target.db

The source manifest stores the exact cache-relative path rather than requiring consumers to recreate this mapping.

Source manifest fields

A manifest contains:

{
  "edition": "2025e",
  "resolved_from": "2025e",
  "acquired_at": "generated-utc-timestamp",
  "artifacts": [
    {
      "part": "PS3.6",
      "format": "docbook_xml",
      "local_path": "artifacts/2025e/raw/source/docbook/part06/part06.xml",
      "source_url": "official-or-null",
      "sha256": "artifact-digest",
      "byte_size": 123
    }
  ],
  "parser_version": "dicom-kb-parser/<package-version>",
  "source_manifest_sha256": "manifest-digest",
  "notice": "project legal notice"
}

The manifest digest is computed from a canonical JSON representation excluding the digest field itself.

Manifest immutability

Writing a manifest or artifact over an existing path fails unless --force is explicit. This protects the relationship between a concrete edition and its recorded source material.

--force is destructive. It can replace cached inputs, rewrite the manifest, and cause an existing database to no longer match until rebuilt.

Database path and metadata

The conventional database path is:

<cache>/db/<edition>.sqlite

Build metadata records:

• concrete edition;
• source-manifest digest;
• schema version;
• build metadata and metrics.

An explicit --db can place SQLite elsewhere, but queries and verification must receive that same path.

Verification statuses

Artifact checks can report:

• ok
• missing
• checksum_mismatch

Database checks can report:

• ok
• missing
• not_checked
• error
• metadata_missing
• metadata_mismatch

Top-level verification is failed when an artifact fails or database metadata is incompatible. A missing database leaves artifact verification useful and is reported with a warning.

Container cache

The repository Dockerfile sets:

DICOM_KB_CACHE_DIR=/data/dicom-standard-kb

and declares that path as a volume. The image contains code, not official artifacts or a prebuilt database. Persist or mount the volume when using a locally built image.

Back up or remove a cache

A cache can be backed up for the same user’s local reproducibility needs, subject to the official source and terminology terms. Do not publish it as a project distribution.

Deleting an edition’s cache removes its source provenance and conventional database. Rebuilding requires reacquiring or reregistering the source artifacts.