Skip to content

Unified Board Item and Player Contract Model

Purpose

This file defines one canonical board-item contract for both system-generated expedition offers and player-posted contracts.

Town boards, event boards, guild boards, and caravan boards should not need separate UI and storage models for NPC work versus player work. They should render one unified item shape with different origin refs and permission rules.

Core Rule

Every board-visible entry should be a board_item.

Creation path can differ:

  • generator writes generated_offer
  • player command writes player_contract

Display, expiry, claim state, filtering, permissions, and acceptance should all read from same board-item projection.

Why Unify

Without shared board item model, project gets duplicate logic for:

  • board ordering
  • urgency tags
  • reason tags
  • expiry and stale cleanup
  • permission checks
  • claim or acceptance state
  • browser read models

One board item contract keeps town, event, guild, and player work on same rails.

Canonical Board Item Contract

Each board_item should contain at least:

  • board_item_id
  • item_kind: generated_offer or player_contract
  • board_source: town_board, guild_board, event_board, regional_caravan_board, or faction_board
  • board_source_ref
  • board_lane: emergency, system, player_contract, guild_civic, or opportunity
  • visibility_scope: public, guild, party, faction, or contract-limited
  • region_id
  • area_id if location-bound
  • target_type
  • target_ref
  • urgency_band
  • urgency_score
  • reward_class
  • reason_tags
  • expires_at
  • capacity_mode: single_claim, multi_claim, or nonexclusive
  • state: active, claimed, expired, completed, cancelled
  • origin_ref
  • seed if generator-authored

Optional but useful fields:

  • issuer_actor_ref for player contracts
  • issuer_guild_ref if guild-posted
  • event_instance_ref
  • control_window_ref
  • town_condition_snapshot_ref
  • recommended_group_size
  • required_knowledge_tags
  • suggested_loadout_tags

Source-Specific Attachments

Generated Offer

generated_offer board items should resolve back to:

  • expedition_offer
  • expedition_generation_run
  • expedition_board_context_snapshot

They inherit urgency, reason tags, and event or control refs from generator output.

Player Contract

player_contract board items should resolve back to:

  • contract_post
  • contract_escrow
  • contract_template
  • completion_rule_set

Player contracts should never bypass board-item projection. Posting contract creates contract rows first, then one or more board items that reference those rows.

Board Lanes and Coexistence Rules

System-generated civic work should not be crowded out by player contracts.

Use explicit board lanes:

  • emergency: crisis or high-severity system work
  • system: normal generated town, event, or route work
  • player_contract: player-posted contracts
  • guild_civic: guild-issued civic or control-window work
  • opportunity: lower-priority surplus or prosperity work

Recommended public board behavior:

  • town boards keep reserved space for emergency and system lanes first
  • player contracts render in dedicated lane or reserved share, not in unrestricted competition with famine or plague response work
  • event boards should usually show system-generated event-response work only, unless the design later allows explicit event-targeted player postings
  • guild boards can mix guild_civic, system, and guild-visible player_contract items

Player Contract Integration Rule

Player job board should reuse same target and completion vocabulary as expedition offers.

Allowed launch contract shapes:

  • hunt target family or named target
  • gather quota from valid source family or area
  • delivery quota to town, project, or civic reserve
  • escort shipment, NPC, or convoy leg
  • survey route, tile cluster, or site verification target

That means player contracts should use same target_type families already defined for expedition generation where possible.

Posting Flow

  1. player issues post_player_contract command
  2. server validates posting rights from skill, renown, and board permissions
  3. server validates template, target scope, reward funding, expiry, and anti-abuse limits
  4. server writes contract_post and contract_escrow
  5. board coordinator writes one or more board_item rows referencing that contract
  6. board read model exposes same projection shape used by generated offers

Claim and Acceptance Modes

Board items should distinguish between visibility and claim behavior.

  • generated_offer usually leads to expedition acceptance
  • player_contract can lead to expedition acceptance, delivery claim, or survey claim depending on template

Recommended field:

  • claim_mode: accept_expedition, reserve_delivery, claim_contract, or direct_turn_in

This keeps one board item shape while allowing different post-click flows.

Unified Board Projection

Client should read board_item_projection, not raw source tables.

Recommended projection fields:

  • board_item_id
  • item_kind
  • board_source
  • board_lane
  • title
  • destination_label
  • urgency_band
  • reward_class
  • primary_reason_tag
  • issuer_summary where relevant
  • time_remaining
  • claim_state
  • visibility_scope

This keeps browser UI fast and lets filters work on one shared schema.

Ordering Rule

Ordering should happen in two stages:

  1. lane priority
  2. score inside lane

Recommended lane priority:

  • emergency
  • guild_civic
  • system
  • player_contract
  • opportunity

Then use urgency, expiry pressure, and source score inside lane.

Expiry and Cleanup

All board items should expire through one cleanup path.

  • generated offers expire from urgency and generator cadence
  • player contracts expire from contract deadline and funding state
  • claimed items may hide from public projection without deleting source records

Expiry should change board_item.state; it should not immediately destroy source rows needed for audit.

Permissions

Board access should be separate from item validity.

Examples:

  • public town board visible to all, but some player contracts may still require renown or skill competence to claim
  • guild board visible only to guild members above configured rank
  • faction board visible by affiliation and standing
  • contract-limited items visible only to named recipients or party

Technical Records

Store:

  • board_item
  • board_item_projection
  • board_item_reason_tag
  • board_item_visibility_grant
  • board_item_claim
  • board_item_expiry_log

Reuse existing source records:

  • expedition_offer
  • contract_post
  • contract_escrow
  • event_instance
  • town_control_window

Commands

Support commands such as:

  • generate_system_offer
  • post_player_contract
  • refresh_board_projection
  • claim_board_item
  • accept_board_item
  • cancel_player_contract
  • expire_board_item

Coordinator Model

Use board coordinators as read-model composers, not as alternate source-of-truth systems.

  • town board coordinator merges generated civic work with eligible public contracts
  • guild board coordinator merges governance work with guild-visible contracts
  • caravan board coordinator merges shipment and route work with delivery or escort contracts

Source systems keep authority. Board coordinators only project and order.

Example Items

Generated Emergency Item

  • item_kind: generated_offer
  • board_source: town_board
  • board_lane: emergency
  • target_type: resource_site
  • urgency_band: critical
  • primary_reason_tag: shortage:medicine

Player Delivery Contract

  • item_kind: player_contract
  • board_source: regional_caravan_board
  • board_lane: player_contract
  • target_type: shipment
  • urgency_band: active
  • primary_reason_tag: player:delivery_contract
  • expedition generation model
  • expedition acceptance and settlement model
  • market, contracts, and logistics
  • social, trade, and governance systems
  • town simulation and supply