query · world.project

Project proposals

Returns the latest retained autonomous project decision and its complete bounded candidate trace for one settlement.

world.project.proposals(filters?, cursor?, page_size?) -> query-page

Stable ID: world.project.proposals
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.0.0

Usage

Query one settlement's latest retained autonomous project decision. Each detached row contains one candidate's hard-gate result and complete fixed-point score plus the shared decision status, explanation, source Settlement revision, selected Construction identity, retained terminal outcome when present, next decision tick, tuning version, useful-project threshold, candidate and consideration counts, and the Building and stockpile owner visits used to compose the facts. Follow next_cursor to inspect every retained candidate.

Parameters

filters.settlement_id: required positive Settlement identity.
cursor: optional continuation cursor indexing the canonical candidate order.
page_size: optional positive candidate-row limit capped by the host.

Returns

A detached candidate page. Decision-level and optional terminal-outcome fields are repeated on every row so continuation pages remain self-describing. Returns capability-unavailable when the Settlement owner or its latest decision is absent.

Cost

One Settlement lookup plus one owner visit per returned candidate, bounded by page size and the calling package's query budgets.

Fields

ID	Type	Units	Required	Description
`building_definition_id`	`string`	none	yes	Candidate building definition identity.
`building_visit_count`	`unsigned-integer`	none	yes	Building owner facts visited while composing the decision.
`candidate_id`	`string`	none	yes	Stable authored proposal identity.
`capacity_pressure_contribution`	`signed-integer`	basis-points	yes	Housing or storage pressure score contribution.
`consideration_evaluation_count`	`unsigned-integer`	none	yes	Fixed-point score components evaluated by the reasoner.
`decision_detail`	`string`	none	yes	Owner-retained decision explanation.
`decision_status`	`enumeration`	none	yes	Selected or no-selection result.
`decision_tick`	`unsigned-integer`	fixed-ticks	yes	Fixed tick evaluated.
`eligibility_detail`	`string`	none	yes	Specific eligibility or rejection reason.
`eligible`	`boolean`	none	yes	Whether the candidate passed every hard gate.
`eligible_candidate_count`	`unsigned-integer`	none	yes	Candidates that passed every hard eligibility gate.
`inverse_labor_cost_contribution`	`signed-integer`	basis-points	yes	Lower-labor-cost score contribution.
`material_readiness_contribution`	`signed-integer`	basis-points	yes	Material-readiness score contribution.
`minimum_score`	`unsigned-integer`	basis-points	yes	Required useful-project score.
`next_project_decision_tick`	`unsigned-integer`	fixed-ticks	yes	Next fixed tick when autonomous planning may run.
`project_outcome_building_definition_id`	`string-or-null`	none	no	Building definition retained with the terminal outcome.
`project_outcome_building_id`	`stable-id-or-null`	none	no	Building identity retained with the terminal outcome.
`project_outcome_cause`	`enumeration-or-null`	none	no	Retained terminal cause of the selected project.
`project_outcome_construction_id`	`stable-id-or-null`	none	no	Construction identity retained with the terminal outcome.
`project_outcome_construction_revision`	`revision-or-null`	none	no	Construction revision observed at the terminal outcome.
`project_outcome_recorded_at_tick`	`unsigned-integer-or-null`	fixed-ticks	no	Tick when Settlement retained the terminal outcome.
`project_outcome_status`	`enumeration-or-null`	none	no	Retained terminal status of the selected project.
`selected`	`boolean`	none	yes	Whether this candidate won the decision.
`selected_construction_id`	`stable-id-or-null`	none	no	Construction created by the selected proposal.
`settlement_id`	`stable-id`	none	yes	Settlement identity.
`settlement_revision`	`revision`	none	yes	Current Settlement owner revision.
`source_settlement_revision`	`revision`	none	yes	Settlement revision evaluated by the reasoner.
`stockpile_visit_count`	`unsigned-integer`	none	yes	Stockpile owner facts visited while composing the decision.
`total_score`	`signed-integer`	basis-points	yes	Candidate's complete fixed-point score.
`tuning_version`	`unsigned-integer`	none	yes	Fixed-point reasoner tuning version.
`visited_candidate_count`	`unsigned-integer`	none	yes	Candidates visited by the bounded reasoner.

Errors

Examples

local result = world.query("world.project.proposals", {
    page_size = 8,
    filters = {settlement_id = settlement.settlement_id}
})
if result.status == "completed" then
    for _, proposal in ipairs(result.records) do
        local outcome = proposal.eligible and tostring(proposal.total_score)
            or proposal.eligibility_detail
        ui.row(proposal.building_definition_id, outcome)
    end
end

API history

1.0.0: Placeholder capability contract published with the Phase 14 registry.
1.5.0: Retained autonomous project decisions and complete candidate traces implemented for Phase 16E.
1.5.0: Added the selected project's retained terminal outcome and reopened decision cadence for Phase 16F.