Expedition Acceptance and Settlement Model

Purpose

This file defines how board items turn into active expeditions and how completed expeditions write results back into town, event, governance, contract, market, and exploration systems.

Core Rule

Once player accepts board item, expedition should run from immutable acceptance snapshot plus authoritative expedition state.

Do not reread mutable board offer or contract rows during settlement except for guarded validity checks. Acceptance freezes what player accepted. Settlement writes what expedition actually achieved.

Lifecycle

1. board item exists on projection
2. player or group issues acceptance command
3. server validates claim, permissions, loadout, supplies, target freshness, and source state
4. server writes immutable expedition_acceptance_snapshot
5. server creates expedition_instance
6. expedition coordinator resolves route, encounters, extraction, and objective work
7. settlement pass computes rewards, failures, and source-system writebacks
8. settlement writes append-only logs and read-model summaries

Acceptance Commands

Recommended commands:

• accept_board_item
• accept_group_board_item
• cancel_prelaunch_acceptance
• lock_group_readiness
• start_accepted_expedition

Commands should validate:

• board item still active and visible
• claim mode is compatible with expedition launch
• target still actionable
• event instance or control window still valid if required
• actor has loadout, supplies, and permissions
• required escrow or reservation exists
• no duplicate exclusive claim already owns target

Acceptance Snapshot Contract

Each expedition_acceptance_snapshot should contain at least:

• acceptance_id
• board_item_id
• item_kind
• board_source
• origin_ref
• actor_ref or group_ref
• accepted_at
• region_id
• area_id
• target_type
• target_ref
• loadout_snapshot_ref
• supply_commitment_ref
• reward_commitment_ref
• difficulty_band
• urgency_band
• reason_tags
• event_instance_ref if any
• control_window_ref if any
• contract_post_ref if player-contract derived
• town_condition_snapshot_ref if town-derived

Useful optional fields:

• target_state_snapshot
• route_state_snapshot
• knowledge_state_snapshot
• group_share_rule_snapshot
• acceptance_seed

Reward Commitment

expedition_reward_commitment should freeze promised payout shape, not final outcome total.

Recommended fields:

• base currency or escrow amount
• item reward table ref
• renown profile
• influence credit profile
• town relief or civic contribution profile
• event contribution profile
• knowledge reward profile
• partial-success rules
• failure rules

This prevents post-acceptance edits to reward terms.

Settlement Channels

Settlement should compute result once, then route writebacks through explicit channels.

Recommended channels:

• personal_rewards
• group_split
• town_relief
• event_resolution
• control_influence
• shipment_or_delivery_completion
• map_knowledge_and_chart_output
• injury_and_gear_wear

One expedition may write to several channels in same pass.

Outcome Bands

Settlement should use readable outcome bands.

• failure
• partial_success
• success
• strong_success
• retreat
• expired_or_aborted

These bands drive reward scaling, contract fulfillment, influence credit, and event points.

Variable Reward Rules

strong_success is not a fixed-probability outcome. It should be reachable through skill, preparation, and circumstance — but not guaranteed. It is the primary source of surprise in the resolution system.

Conditions that can push an outcome from success to strong_success:

• All encounters resolved with no injuries and above-average result rolls
• Character has Mastered knowledge of the target creature family (codex entry at Mastered)
• Expedition completed with supply usage below 60% of committed amount
• Relevant skill is Veteran or above and the expedition difficulty band is below the character's competence band

Additional variable events that can fire on any outcome band success or above:

Event	Trigger condition	Effect
Rare material drop	Hunt/gather; target tier Elite or above	One additional material at quality Fine or above added to output
Mid-route site hint	Traversal of a hex adjacent to an undiscovered site	Nearby hex upgraded to rumored state; no content revealed, coordinates only
Rare codex entry	First encounter with a variant in an already-known family	Codex entry added; family completion fraction updates
Quality roll uplift	Gather; Survey skill at Practiced or above	Gathered output quality bumped one tier on a low-probability roll

None of these are announced before the expedition. They appear in the result screen only. The unpredictability is intentional — variable reward schedules sustain engagement better than fixed returns.

Settlement Flow

1. freeze expedition end state and confirm not already settled
2. total route results, encounter results, extraction results, and objective completion
3. derive outcome band
4. compute player and group rewards from reward commitment plus outcome
5. compute source-system writebacks
6. release escrow, write logs, and publish read models

Stat Ledger Writes

During step 6, settlement writes character_stat_event rows for every participant. These feed leaderboards via the cron aggregation pipeline.

Writes per settlement:

Outcome	Rows written
Any resolved	expeditions_completed or expeditions_failed (delta = 1)
Coin reward distributed	coin_earned (delta = coin amount)
Items rewarded	items_gathered (delta = total item count)
Crafting completion	items_crafted (delta = quantity produced)
Town supply delivered	town_influence (delta = normalized reserve units)
Board order fulfilled	board_orders_filled (delta = 1)
Elite encounter cleared	elite_kills (delta = elite count in result)
Boss encounter cleared	boss_kills (delta = 1)

All rows written in same D1 transaction as the main settlement commit. If the transaction rolls back, stat rows roll back with it — no orphaned counts.

Generated Offer Writebacks

Generated offers should write back into source systems explicitly.

Town Relief

If expedition addressed shortage, project, or civic route pressure, settlement can write:

• reserve units delivered or recovered
• project progress credit
• route stabilization credit
• contract urgency relief

Event Resolution

If expedition linked to event instance, settlement should write:

• event_participation row
• normalized resolution points
• any special success flag such as rescue count, hazard confirmation, or monster pressure reduction

Control and Governance

If expedition linked to control window or contested civic work, settlement should write:

• town_influence_ledger credit
• civic reserve support credit if delivery or project work succeeded
• control-window participation totals

If contract allows multiple fulfillers, settlement should update remaining quota rather than hard-close contract unless threshold reached.

Map and Knowledge Writebacks

Survey and exploration expeditions should write:

• character_tile_knowledge updates
• chart-item creation rights or outputs
• archive submission eligibility if rules allow auto-share
• route verification or stale-data refresh

Bought or claimed contract work should still respect same distinction between revealed, charted, and imported knowledge defined in exploration docs.

Delivery and Shipment Writebacks

Escort, caravan, and delivery expeditions should be able to settle:

• shipment completion
• protected cargo survival percentage
• town reserve credit
• market delivery confirmation
• contract completion or civic reserve turn-in

This is where logistics gameplay joins town and market systems instead of ending as flavor text.

Group Rules

Group acceptance should snapshot:

• roster
• readiness state
• loadout refs
• supply contributions
• share rules for rewards and costs

Settlement should then use that snapshot for:

• reward splitting
• injury attribution
• contract credit rules
• influence credit distribution

No member replacement after launch unless mission type explicitly allows reinforcements.

Idempotency and Recovery

Settlement must be replay-safe.

Recommended records:

• expedition_settlement_run
• expedition_settlement_result
• expedition_source_writeback

Rules:

• first successful settlement writes final result marker
• later retries return same result and skip duplicate side effects
• every external writeback should carry stable write key derived from acceptance_id plus channel name

Read Models

Expose summaries such as:

• active accepted expeditions
• completed expedition recap
• player contract status recap
• town-relief contribution summary
• event participation summary
• control-window contribution summary

These should read from settlement results, not from raw resolver internals.

Technical Records

Store:

• expedition_instance
• expedition_acceptance_snapshot
• expedition_reward_commitment
• expedition_settlement_run
• expedition_settlement_result
• expedition_source_writeback
• contract_fulfillment

Reuse existing records where relevant:

• event_participation
• town_influence_ledger
• shipment
• character_tile_knowledge
• contract_post
• contract_escrow

Related Systems

• unified board item and player contract model
• expedition generation model
• combat resolution
• market, contracts, and logistics
• town simulation and supply
• dynamic events and world state