query · world.settlement

Settlement housing executions

Returns the bounded Settlement-owned lifecycle that binds a selected housing method to its Household and authoritative Construction or completed Building outcome.

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

Stable ID: world.settlement.housing-executions
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

Inspect the bounded Settlement-owned lifecycle that binds a selected housing method to one Household and the authoritative Construction or completed Building outcome. Supply settlement_id and optionally household_id. The query cannot start, advance, cancel, or mutate housing work.

Parameters

filters.settlement_id: required stable Settlement identity.
filters.household_id: optional stable Household identity.
cursor: optional continuation cursor over stable execution identities.
page_size: bounded execution-row limit.

Returns

Detached execution rows with stable identity, selected method and optional parcel keys, Household, method, target Building, building definition, Construction, resulting Building, lifecycle, source evaluation ticks, source Household revision, latest owner revision, explanation, and creation and update ticks.

Cost

One exact Settlement lookup plus one bounded traversal of the retained execution ledger in stable identity order. Runtime starts and reconciliation use separate authored visit and mutation budgets.

Fields

ID	Type	Units	Required	Description
`building_definition_id`	`string`	none	yes	Building definition used.
`construction_id`	`stable-id-or-null`	none	no	Bound Construction identity.
`created_at_tick`	`unsigned-integer`	fixed-ticks	yes	Execution creation tick.
`detail`	`string`	none	yes	Direct lifecycle or blocker explanation.
`execution_id`	`stable-id`	none	yes	Durable housing execution identity.
`household_id`	`stable-id`	none	yes	Destination Household identity.
`method`	`enumeration`	none	yes	Selected housing method.
`method_option_key`	`string`	none	yes	Selected housing-method identity.
`owner_revision`	`revision`	none	yes	Latest authoritative outcome revision.
`parcel_option_key`	`string-or-null`	none	no	Selected parcel identity.
`resulting_building_id`	`stable-id-or-null`	none	no	Completed Building identity.
`settlement_id`	`stable-id`	none	yes	Settlement identity.
`settlement_revision`	`revision`	none	yes	Current Settlement owner revision.
`source_household_revision`	`revision`	none	yes	Household revision selected.
`source_method_evaluation_tick`	`unsigned-integer`	fixed-ticks	yes	Housing-method evaluation used.
`source_parcel_evaluation_tick`	`unsigned-integer`	fixed-ticks	yes	Parcel evaluation used, or zero for methods without parcels.
`status`	`enumeration`	none	yes	Active, completed, blocked, cancelled, or failed.
`target_building_id`	`stable-id-or-null`	none	no	Existing target Building.
`updated_at_tick`	`unsigned-integer`	fixed-ticks	yes	Latest lifecycle update tick.

Errors

Examples

local executions = world.query("world.settlement.housing-executions", {filters = {settlement_id = 1}, page_size = 16})
for _, execution in ipairs(executions.records) do
    ui.text(execution.method, execution.status .. ": " .. execution.detail)
end

API history

1.19.0: Durable housing execution bindings, blockers, and authoritative outcomes added for Phase 19Q5D.