query · world.settlement

Settlement goals

Returns the latest Settlement-owned goal portfolio, including committed goals and rejected or deferred alternatives.

world.settlement.goals(filters?, cursor?, page_size?) -> query-page

Stable ID: world.settlement.goals
Owner: game.settlement
Authority: read_only
Timing: immediate
Availability: active-session
Side effects: none
Determinism: stable owner order at the current committed tick
Introduced: 1.19.0

Usage

Read the latest Settlement-owned portfolio of committed, paused, retired, and rejected civic goals without creating work or mutating any owner. Supply settlement_id to select the settlement.

Parameters

filters.settlement_id: required stable Settlement identity.
cursor: optional continuation cursor over candidates in stable goal-key order.
page_size: bounded candidate-row limit.

Returns

Detached candidate rows with stable goal identity when retained, source and sponsor kinds, need domain, source strength, weighted score, benefit, cost, risk, opportunity cost, reconsideration threshold, dependency and incompatibility counts, status, eligibility, selection, and direct decision detail.

Cost

One exact Settlement lookup plus one bounded traversal of the latest retained goal-candidate page. Recurring evaluation uses the settlement definition's rotating visit budget and fixed cadence.

Fields

ID	Type	Units	Required	Description
`completed_evaluation_count`	`unsigned-integer`	none	yes	Durable portfolio sequence count.
`dependency_count`	`unsigned-integer`	none	yes	Declared prerequisite goal count.
`detail`	`string`	none	yes	Direct selection or rejection reason.
`domain`	`enumeration`	none	yes	Typed settlement need domain.
`eligible`	`boolean`	none	yes	Whether the candidate passed source and score gates.
`evaluation_tick`	`unsigned-integer`	fixed-ticks	yes	Fixed tick evaluated.
`expected_benefit`	`unsigned-integer`	basis-points	yes	Expected benefit.
`expected_cost`	`unsigned-integer`	basis-points	yes	Expected cost.
`goal_id`	`stable-id-or-null`	none	no	Durable goal identity when one exists.
`goal_key`	`string`	none	yes	Data-authored goal identity.
`incompatibility_count`	`unsigned-integer`	none	yes	Declared incompatible goal count.
`next_evaluation_tick`	`unsigned-integer`	fixed-ticks	yes	Next fixed tick when evaluation may run.
`opportunity_cost`	`unsigned-integer`	basis-points	yes	Opportunity cost.
`priority_score`	`signed-integer`	basis-points	yes	Weighted portfolio score.
`reconsider_below`	`unsigned-integer`	basis-points	yes	Source threshold below which a retained goal retires.
`risk`	`unsigned-integer`	basis-points	yes	Expected risk.
`selected`	`boolean`	none	yes	Whether the portfolio committed the candidate.
`settlement_id`	`stable-id`	none	yes	Settlement identity.
`settlement_revision`	`revision`	none	yes	Current Settlement owner revision.
`source_kind`	`enumeration`	none	yes	Need, opportunity, obligation, or ambition.
`source_need_assessment_tick`	`unsigned-integer`	fixed-ticks	yes	Need assessment used as source evidence.
`source_settlement_revision`	`revision`	none	yes	Settlement revision used to evaluate the portfolio.
`source_strength`	`unsigned-integer`	basis-points	yes	Current source strength.
`sponsor_id`	`string`	none	yes	Stable sponsor identity.
`sponsor_kind`	`enumeration`	none	yes	Household, business, civic, or institution.
`status`	`enumeration`	none	yes	Committed, paused, retired, or rejected.

Errors

Examples

local goals = world.query("world.settlement.goals", {filters = {settlement_id = 1}, page_size = 16})

API history

1.19.0: Durable concurrent settlement goals, sponsors, dependencies, reconsideration, and rejected alternatives added for Phase 19Q2.