Audit and Signature

After a successful forge, EmakiForge writes audit data into the result item so the source recipe can be traced and tampering with material contribution data can be detected

Where the data lives

Forge audit data exists in two places:

1. CoreLib item layer snapshot: namespace forge, layer version 1, whose payload is the audit field table below. Item refresh reads it back from here
2. The emakiforge:forge PDC partition: key fields flattened so the placeholder and variable systems can read them. See Forge layer PDC keys

Audit fields

After a successful forge the following fields are written into the audit payload:

Field	Description
schema	Audit structure marker, currently always forge_audit_v2
schema_version	Audit structure version, currently 2
stage	Originating stage, currently always forge
recipe_id	Recipe id used for forging
quality	Quality tier name; an empty string when no tier resolved
multiplier	Quality multiplier
forged_at	Forge timestamp in milliseconds
materials_signature	Stable hash signature of material contribution data
output_item	Output item source shorthand. Written only when the recipe configures an output item source
materials	Material contribution list, see the table below

Fields of each materials[] entry:

Field	Description
material_id / count_key / audit_id	Material identity keys. Written only when declared explicitly in config; the key is removed when it was not declared
material_item	Compatibility identity: the item source shorthand, or matcher:<digest>
category	Material category (required / optional)
amount	Planned amount
amount_consumed	Actually consumed amount
slot	GUI slot the material occupied
sequence	Processing order
matched_source	Item source shorthand actually matched
matcher	Matcher digest key; an empty string when there is no matcher
allocation	Slot allocation detail for this entry
legacy_identity / identity_diagnostic	Compatibility identity and diagnostic marker added when some identity key was not declared

Material signature

materials_signature is computed only from material contributions whose consumed amount is greater than zero; the signature input covers the material definition digest, amount, consumed amount, slot, category, sequence, matched source, and allocation detail. The same set of material contributions always yields the same signature, so it can be used to compare an item's forging material data against an expected value

Forge layer PDC keys

Flat keys under namespace emakiforge, partition forge:

Key	Type	Description
forge_recipe_id	string	Recipe id that forged the item
quality_id	string	Quality id (same value as the tier name)
quality_display	string	Quality display name
quality_multiplier	string	Quality multiplier, stored formatted as 0.##
material_id	string	Comma-joined list of explicitly declared material_id values; removed when empty
count_key	string	Comma-joined list of explicitly declared count_key values; removed when empty
audit_id	string	Comma-joined list of explicitly declared audit_id values; removed when empty
matched_source	string	Comma-joined list of matched source shorthands
amount_consumed	integer	Total consumed amount across all materials
matcher_digest	string	Comma-joined list of matcher digests
allocation	string	Stable signature of the allocation detail

The CoreLib variable system exposes these as the variables forge_quality_id, forge_quality_display, forge_quality_multiplier, and forge_recipe_id, plus the partition-relative PDC strings

Relationship with refresh

The Forge item refresh service reads recipe_id and quality from the audit data to rebuild the forge layer presentation. Items whose audit data is missing, whose quality is no longer in the current pool, or whose recipe has been deleted cannot have their forge layer rebuilt and produce a warning

When resolving material audit records, the current implementation falls back in this order: audit_id → material_id → count_key → legacy material_item / source. A successful legacy lookup is marked for migration and rebuilt during refresh; when no identity resolves, the original item is kept and a warning is logged rather than overwriting it with incomplete state. Material identity keys must stay stable: a matcher-only material derives its identity from the matcher content digest, so editing the matcher makes already-forged items report a missing material (console.forge_refresh_missing_material). This behaviour is established by source inspection, but old PDC audit data was not tested on a live Paper/Folia server in this cycle

Use cases

• Trading or recycling systems can read audit data to determine an item's source recipe and quality
• External analytics can aggregate forge output by recipe_id, quality, and forged_at

NOTE

Forge does not ship a built-in command for viewing audit data. Use an external tool that can read item PDC and item layer snapshots when manual inspection is needed