K3Z Metadata and Lineage

Scope

This page documents the current metadata inventory, build lineage, and provenance policy for the tracked K3Z sample model package at models/k3z_patchworks_model plus the validated export mirrors under output/patchworks_k3z*_validated.

Machine-readable companion registry:

  • models/k3z_patchworks_model/metadata/lineage_registry.yaml

Inventory: Upstream Sources -> Model Artifacts

The key dataset families feeding output/, tracks/, and blocks/ are:

Target artifact family

Current in-repo path

Upstream source datasets

Primary compiler step

Fragments shapefile

output/patchworks_k3z_validated/fragments/fragments.*

data/model_input_bundle/au_table.csv plus stand checkpoint data/ria_vri_vclr1p_checkpoint7.feather (or explicit --checkpoint)

femic export patchworks

ForestModel XML

output/patchworks_k3z_validated/forestmodel.xml

data/model_input_bundle/{au_table,curve_table,curve_points_table}.csv plus optional seral config

femic export patchworks

Blocks shapefile

models/k3z_patchworks_model/blocks/blocks.*

models/k3z_patchworks_model/data/fragments.shp

femic patchworks build-blocks

Block topology CSV

models/k3z_patchworks_model/blocks/topology_blocks_200r.csv

models/k3z_patchworks_model/blocks/blocks.shp geometry adjacency

femic patchworks build-blocks --topology-radius 200

Build-Lineage Chain

Current canonical lineage for the tracked K3Z model:

  1. Bundle/checkpoint stage (FEMIC pipeline output): data/model_input_bundle/*.csv + checkpoint feather.

  2. Patchworks export stage: femic export patchworks --tsa k3z --seral-stage-config config/seral.k3z.yaml. This produces output/patchworks/forestmodel.xml and output/patchworks/fragments/fragments.*.

  3. Validated-export stage: output/patchworks/forestmodel.xml -> output/patchworks_k3z_validated/forestmodel.xml and output/patchworks/fragments/* -> output/patchworks_k3z_validated/fragments/*.

  4. Blocks stage: femic patchworks build-blocks --config config/patchworks.runtime.windows.yaml.

  5. Matrix stage: femic patchworks matrix-build --config config/patchworks.runtime.windows.yaml. Tracks CSVs are rebuilt in models/k3z_patchworks_model/tracks.

  6. Account-promotion stage (automatic in matrix-build): tracks/protoaccounts.csv -> tracks/accounts.csv with timestamped backup.

Component-Level Notes

  • Fragments compiler semantics: build_fragments_geodataframe(...) scopes checkpoint rows by the legacy case/FMU code field and AU, computes area/age fields, and resolves IFM assignment from THLB signal columns (or explicit IFM options).

  • ForestModel compiler semantics: built from normalized AU/curve context derived from bundle tables; optional seral-stage boundaries are loaded from YAML.

  • Blocks compiler semantics: strict stand:block identity mode; BLOCK is copied from stand identifier field (FEATURE_ID/FRAGS_ID) in fragments.

  • Matrix compiler semantics: Matrix Builder consumes fragments.dbf + forestmodel.xml and writes tracks/*.csv; FEMIC evaluates completion by artifact readiness and fatal log signatures.

Provenance Versioning Policy

Use this policy for each rebuild intended for teaching/collaboration release:

  1. Treat these as authoritative source inputs: run-profile/config values, bundle tables, checkpoint feather, and seral config YAML.

  2. Rebuild in deterministic order: export patchworks -> sync model inputs -> build blocks -> matrix-build.

  3. Preserve run evidence: keep run-scoped manifests/logs under runtime/logs for rebuild events.

  4. Commit artifact + metadata updates together: model artifacts changed by rebuild, updates to this page and lineage_registry.yaml, the governing ROADMAP.md phase/task entry, any linked planning note, and matching CHANGE_LOG.md entry.

  5. Never hand-edit generated families in release prep: tracks/*.csv, blocks/blocks.*, and generated topology CSV. Regenerate instead.

Acceptance Checklist for Lineage Updates

  • Source inventory still maps all current output/, tracks/, and blocks/ artifacts.

  • Command chain and runtime config references remain accurate.

  • Registry file is updated for any path/command/schema changes.

  • Related roadmap/changelog notes are appended in the same milestone.