sow-tools/internal/topdata/PORTRAIT_METADATA_CONTRACT.md

Portrait Metadata Contract

Objective

Define the canonical behavior for portrait metadata embedded in topdata rows, enabling explicit opt-in portrait injection into the portraits.2da table.

---

Portrait Metadata Shape

Portrait metadata is embedded in row meta.portrait:

{
  "meta": {
    "portrait": {
      "resref": "nw2book1_",
      "sex": 4,
      "race": 10,
      "inanimate_type": 4,
      "plot": 0,
      "low_gore": "****"
    }
  }
}

Required Fields

• resref — non-empty string identifying the portrait base resource reference

Optional Fields

• sex — numeric or string value mapped to portraits.2da Sex column
• race — numeric or string value mapped to portraits.2da Race column
• inanimate_type — numeric or string value mapped to portraits.2da InanimateType column
• plot — numeric or string value mapped to portraits.2da Plot column
• low_gore — numeric or string value mapped to portraits.2da LowGore column

Field names are case-insensitive with hyphen/underscore normalization:

• inanimate_type = inanimate-type = InanimateType

---

Merge Behavior

Identity Matching

Portrait entries are matched by resref. Injection is only enabled when all of the following are true:

1. The row carries meta.portrait.resref
2. The row comes from a JSON module under topdata/data/<dataset>/modules
3. The dataset is one of appearance, genericdoors, or placeables

When those conditions are met:

1. If a portraits.2da row with matching BaseResRef already exists → merge into that row
2. If no matching row exists → create a new row with auto-generated identity portraits:auto:<resref>

Field Mapping

Portrait metadata fields map to portraits.2da columns:

Metadata Key	2DA Column
resref	BaseResRef
sex	Sex
race	Race
inanimate_type	InanimateType
plot	Plot
low_gore	LowGore

Override Precedence

• First contributor wins for each column
• If a column already has a non-null value, subsequent contributions are rejected if they differ
• Identical values (after normalization) are silently accepted
• Conflicting values produce a build error

Null-Like Values

Missing fields and nullValue ("****") are treated as unset. They do not override existing values and are not considered conflicts.

---

Lock Data

Auto-generated portrait rows are tracked in lock data with key pattern:

portraits:auto:<resref>

For example: portraits:auto:nw2book1_

---

Cross-Dataset Injection

Only module-authored rows from appearance, genericdoors, and placeables may contribute portrait metadata. The build pipeline:

1. Collects all datasets
2. Runs mergePortraitMetadata() after dataset collection
3. Injects portrait rows into the portraits.2da dataset
4. Updates lock data if new auto-generated rows were created
5. Prunes stale portraits:auto:* lock entries when no active auto-injected portrait row remains

This enables supported non-portrait datasets to define portrait associations without modifying the portraits dataset directly, while making the behavior explicit and removable with the originating module.

---

Validation Rules

1. resref is required — missing resref produces a parse error
2. Unknown metadata fields in meta.portrait produce a parse error
3. Unknown top-level keys in meta produce a parse error (allowed keys: family, wiki, portrait)
4. Base rows do not inject portraits, even if they carry meta.portrait
5. Conflicting portrait field values from different contributors produce a build error
6. Portrait metadata is excluded from emitted 2DA output — it exists only at authoring/build time

---

Acceptance Criteria

Implementation is correct only if all of the following are true:

1. Portrait metadata is parsed from meta.portrait with case-insensitive field names
2. Only module-authored rows from appearance, genericdoors, and placeables inject into portraits.2da by resref matching
3. Base rows do not trigger portrait injection
4. Auto-generated rows receive portraits:auto:<resref> lock keys
5. First-contributor-wins precedence is enforced per column
6. Conflicting values produce build errors with clear diagnostic messages
7. Portrait metadata does not leak into emitted 2DA column output
8. Lock data is persisted when new auto-generated rows are created and stale auto-generated keys are pruned