Ingest Deep Dive

This chapter focuses on ingest behavior and reproducibility controls.

How ingest resolves sources

Ingest uses mapping catalogs to determine:

  • source roots,

  • backend glob selection,

  • ignore suffix handling,

  • alias and priority behavior.

Verification behavior

After copy, ingest verifies expected tim presence and reports missing files.

Interpret missing-file warnings as one of:

  • mapping mismatch,

  • source-tree drift,

  • renamed files,

  • expected optional sources not present.

Lockfiles

Lockfiles capture resolved source match sets for reproducibility.

Strict mode behavior:

  • aborts ingest when source-tree content differs from lock snapshot.

Recommended lifecycle:

  1. exploratory ingest with relaxed strictness,

  2. stabilize mapping,

  3. freeze lock snapshot,

  4. enforce strict lock validation for production reruns.

Branch behavior

Ingest commit target is controlled by ingest base/branch settings. Ensure the intended git repo root is used (not a nested output path with independent git state).

Troubleshooting checklist

  • confirm mapping paths exist,

  • confirm output root is the intended repo tree,

  • confirm base branch exists in that repo,

  • inspect lock validation report on abort.

See also

  • Ingest mapping schema: configs/schemas/ingest_mapping.schema.json

  • Config layout: Configuration Layout