aetherbound-guild/docs/content/RECRUIT_GENERATION.md

Generated Recruit Authority

Contract: every recruit is a run-scoped composition, not an authored story identity. Many recruits may share a profession. Generation must remain deterministic from the saved run seed and offer index.

Revision: recruit-line-design-r3 / 2026-08-11

1. Recruit Record

recruit_instance_id, generation_seed, offer_index, source_offer_id
source_draft_id or Market_id, canonical_output_hash
display_name_tokens, pronoun_set, voice_effort_set
body_frame, face_shape, skin_palette, hair_shape, hair_palette
garment_cut, garment_palette, profession_overlay, detail_mark
base_profession_id, attribute_vector, trait_id
starting_equipment_id, level, xp, mastery_by_profession
quality_band, shop_cost_tier, duplicate_signature
survival_battles, knockouts, scars[], acquired_tick

recruit_instance_id is unique even when two offers have the same visible composition. duplicate_signature hashes name tokens, visual parts, profession, trait, and attribute grade pattern; equipment and level are not part of it. Survival history changes the run record and optional scar overlay, never the recruit's rules invisibly.

2. Deterministic Generation Order

Generation consumes substreams in this fixed order so a presentation change cannot reroll combat power:

1. choose base profession from the shop's visible role-weight table;
2. roll attribute grade pattern from the profession's legal templates;
3. choose one legal trait after profession exclusions;
4. choose quality band from the offer's disclosed band weights;
5. choose starting level from region depth and recovery pressure;
6. choose starting equipment from the profession's starter tags and quality;
7. assemble display-name tokens and pronoun set;
8. assemble modular body, face, hair, garment, palette, overlay, and detail;
9. run duplicate protection and, if rejected, reroll only presentation tokens;
10. derive cost tier from level, quality, equipment, and scarcity using the product economy formula.

The combat substream ends after step 6. Steps 7-9 can never alter profession, attributes, trait, level, equipment, or price tier.

2.1 Opening Four-Offer Binding

Opening generation is legal only from a validated, read-back run_creation_draft created by an applied seed-reservation operation. The generator cannot reserve a seed, read wall clock, consume an ambient random stream, or run speculatively before that boundary. For each unsigned opening index i in the closed set 0..3, derive:

opening_offer_id_i = low128(sha256(run_seed || "opening-offer-id" || u8(i)))
generation_seed_i  = low128(sha256(run_seed || "opening-recruit" || u8(i)))
recruit_instance_id_i = low128(
  sha256(run_seed || "opening-recruit-instance" || u8(i)))
canonical_output_hash_i = sha256(canonical_bytes(complete Recruit record_i,
                                                   excluding this hash))

The draft's saved Contract, difficulty, ruleset, content revision, and opening role-weight snapshot are immutable inputs to the generation procedure. They may affect the generated record but cannot change the ID/seed mapping above. All four complete records, their ordered indices, offer IDs, and output hashes enter one materialization commit; a partial array is invalid. Re-running generation after interruption must reproduce byte-equivalent canonical records and all four hashes or fail OPENING_OFFER_HASH_MISMATCH without replacing the seed.

The accepted opening choice is an unordered set of exactly two distinct saved offer IDs. Selecting or revising that set consumes no random draw and never mutates any Recruit record. Run commit transfers the two records with their existing recruit_instance_id, generation seed, index, offer ID, and output hash. The two unchosen records remain in the draft until that commit applies; only the applied commit discards them.

3. Display-Name Pool

Names use one given token plus one byname token. Localizers may substitute a curated culturally coherent pool rather than transliterate combinatorial fragments; the saved identity stores message IDs, not rendered strings.

Pool	Independently authored tokens
Given A	Aven, Brin, Cassa, Dorel, Eiren, Fara, Gannet, Hessa, Iven, Jora, Kelm, Lio
Given B	Marn, Neris, Orra, Pella, Quin, Rusk, Sella, Tavin, Ulan, Vessa, Wren, Yori
Byname A	Amberfield, Bellwake, Coldmere, Dawnreed, Emberstep, Faircurrent, Glassfern, Highspoke
Byname B	Ironleaf, Juniper, Kindler, Larkfall, Mossward, Northcoil, Oatbridge, Pineglass
Byname C	Quillwater, Rill, Stonebloom, Tidewell, Umberlane, Valehook, Windrow, Yarrow

The base pool yields 576 visible combinations before localization. A run may reuse a given token or byname, but not the exact pair until every legal pair in the current language pool has appeared. The name is never used as a combat seed, target key, unlock key, or uniqueness restriction.

4. Modular Visual Grammar

Part	Options	Production and readability rule
Body frame	8	Four height bands by two mass bands; identical collision and timing
Face shape	12	Must read at portrait scale without encoding combat quality
Skin palette	12	Hand-authored values checked across daylight, dusk, and status overlays
Hair/head shape	24	Includes bald, covered, braided, curled, straight, and textured families
Hair palette	10	Natural and aether-touched options; no rarity coding
Garment cut	12	Shared neutral underlayers compatible with every profession overlay
Garment palette	16	Contrast-paired main/accent sets with color-blind luminance separation
Profession overlay	42	One modular silhouette cue per PF-*; it communicates active ruleset
Detail mark	20	Scar, freckle, paint, jewelry, patch, or tool token; cosmetic only
Voice effort set	8	Nonverbal effort/death/confirmation sets shared broadly; no personal scenes

The assembler rejects combinations that obscure face, weapon action, front/rear orientation, status halo, or profession silhouette. Pronoun sets are selected independently of body and voice options. Critical information is always text, shape, and timing readable; color and sound are supplemental.

5. Attribute Roll

Every recruit has five displayed grades: Vigor, Force, Finesse, Focus, and Resolve. The core system maps grades to numbers. Content generation owns only grade allocation.

Template	Grade multiset	Decision meaning	Quality availability
Even	B, B, B, C, C	Flexible, no extreme liability	Common and above
Pointed	A, B, C, C, D	Strong thesis with one exposed failure	Common and above
Twin	A, A, C, D, D	Two-role spike with expensive protection needs	Uncommon and above
Durable	A in Vigor or Resolve; B, B, C, D elsewhere	Survival consistency, slower payoff	Common and above
Precise	A in Finesse or Focus; B, B, C, D elsewhere	Target/timing consistency, fragile edge	Common and above
Volatile	S, B, D, D, D	Build-around extreme; never an opening forced buy	Rare only

Each base profession declares two preferred attributes. A legal template places at least one A or B in a preferred attribute and never places both preferred attributes at D. Grades do not improve with recruit quality; quality changes how pointed a legal pattern may be, starting gear breadth, and price pressure. No hidden luck, growth-rate, or personality stat exists.

6. Trait Selection

Exactly one TR-* row is attached at generation. Selection procedure:

1. remove traits whose prohibited profession, action, or equipment tag matches;
2. weight remaining traits toward an exposed cost the preview can explain;
3. suppress any trait already held by two living owned recruits when at least twelve other legal traits remain;
4. show both benefit and cost in the offer before purchase;
5. preserve the trait through profession advancement and switching.

Traits are never upgraded, stacked, inherited, or secretly paired. An artifact that references traits changes a run-wide selection rule; it does not give a recruit a second trait.

7. Starting Profession And Advancement

Opening and ordinary offers use one of PF-B01..PF-B12. Regular advanced professions are learned only through the parent mapping in PROFESSION_CATALOG.md. Hidden hybrids require mastery of both listed bases, the row's run deed, and an explicit conversion choice; they never appear as random shop offers.

Shop role weights use visible unmet-demand tags: front-hold, single-pressure, reach, reorder, projectile, area, restore, enable, construct, impair, tempo, and supply. A reroll may change offers but cannot change the advertised weight table until the next battle result.

8. Starting Equipment

Starting equipment is drawn only from these disclosed pools. The item catalog owns each actual rule and eligibility condition.

Offer depth	Legal IDs	Count equipped	Constraint
Opening	EQ-001..EQ-040	1	Must be legal for the rolled profession and cannot repeat another opening offer's item while alternatives exist
Early	EQ-001..EQ-080	1	At least one offer per shop has a behavior-class B item
Middle	EQ-041..EQ-200	1	Item must expose its behavior hook and wearer tradeoff in preview
Late	EQ-121..EQ-280	1	Item must be legal for the rolled Profession and current ruleset
Mastery/postgame	EQ-161..EQ-320	1	EQ-281..EQ-320 appear only after their visible unlock deed

Starting gear is part of the displayed price. Removing it before purchase is not allowed; after purchase, normal equip and salvage rules apply.

9. Level, Quality, Cost, And Rarity Boundaries

Quality	Visible mark	Generation boundary	Cost consequence	Duplicate boundary
Common	one notch	Even, Pointed, Durable, or Precise; one starter item from the common eligible band	baseline cost tier	exact combat signature may recur after three other offers
Uncommon	two notches	Any non-Volatile template; one starter item with a disclosed behavior hook	+1 tier	same profession+trait suppressed while a legal alternative exists
Rare	three notches	Includes Volatile; one behavior-class B starter item from the rare eligible band	+2 tiers	exact combat signature once per run unless pool exhaustion is shown

There are no higher recruit rarities. Quality does not grant a universal stat multiplier. Starting level is max(1, region_floor - 1) through region_floor + 1, bounded by the product progression cap. A death-recovery shop guarantees at least one recruit at or below the player's current recovery cost tier; content never sets the currency value itself.

10. Duplicate And Exhaustion Rules

• Same profession is always legal and strategically expected.
• Same name pair is presentation-only and blocked until name-pool exhaustion.
• Same profession+trait is blocked in a single shop while another legal trait exists; it may recur across shops.
• Exact combat signature is suppressed according to quality in Section 9.
• Same visual assembly is blocked for the whole run; on exhaustion, reroll the detail mark, then garment palette, then hair palette, in that order.
• Locked shop offers retain their complete saved record. Refreshing, loading, localization changes, or clock changes cannot reroll them.
• Opening provisional offers retain their complete saved records in the run_creation_draft. Back, Cancel, retry, restart, selection revision, and clock changes return the same IDs and hashes and cannot invoke refresh logic.
• Pool exhaustion is visible and deterministic. It relaxes presentation uniqueness before combat uniqueness and never invents an unavailable ID.

11. Offer Preview And Production Handoff

Every recruit offer exposes: profession responsibility and band preference; attribute grades; trait benefit and cost; starting equipment behavior; current level; total product-calculated cost; quality boundaries; predicted first basic target; and one sentence explaining the roster decision the recruit adds. Modular production needs are P/O/A/V/S: portrait parts, profession overlay, shared action timing, profession feedback, and shared effort events.

An opening provisional preview additionally binds its displayed card to source_draft_id, offer_index, source_offer_id, and canonical_output_hash. Those identifiers are semantic state, not player-facing technical copy; presentation may expose a short recovery/reference code when an integrity error must be reported.

No generated recruit requires authored biography, social progression, romantic content, personal quest, unique dialogue, or individual casting. The run history may record purchase, battles survived, knockouts, equipment, profession changes, and death as factual events without generating narrative claims.