Skip to content

Unified Board Item Model

Purpose

This file defines one canonical board-item contract for system-generated expedition offers.

Town boards, event boards, guild boards, and caravan boards should not need separate UI and storage models across different board sources. 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:

  • generator writes generated_offer

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 caravan work on same rails.

Canonical Board Item Contract

Each board_item should contain at least:

  • board_item_id
  • item_kind: generated_offer
  • board_source: town_board, guild_board, event_board, or regional_caravan_board
  • board_source_ref
  • board_lane: emergency, system, guild_civic, or opportunity
  • visibility_scope: public, guild, party, 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:

  • 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.

Board Lanes and Coexistence Rules

System-generated civic work should be prioritized by urgency and board lane.

Use explicit board lanes:

  • emergency: crisis or high-severity system work
  • system: normal generated town, event, or route work
  • 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
  • event boards should show system-generated event-response work
  • guild boards can mix guild_civic and system items

Claim and Acceptance Modes

Board items should distinguish between visibility and claim behavior.

  • generated_offer can lead to expedition acceptance, delivery claim, or survey claim depending on the offer template

Recommended field:

  • claim_mode: accept_expedition, reserve_delivery, 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
  • 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
  • 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
  • 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
  • event_instance
  • town_control_window

Commands

Support commands such as:

  • generate_system_offer
  • refresh_board_projection
  • claim_board_item
  • accept_board_item
  • 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 from all sources
  • guild board coordinator merges governance work
  • caravan board coordinator merges shipment and route work

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
  • expedition generation model
  • expedition acceptance and settlement model
  • market, contracts, and logistics
  • social, trade, and governance systems
  • town simulation and supply