# lawref.goals

*module*

Цели акта как объект (DECISION-0089) — оркестрация над свойствами [§270](https://github.com/arxohq/law/blob/master/spec/SPEC.ru/36-part-xxxiv-conformance-tests.ru.md#270-property-based-tests).

Цель есть свойство с основанием `basis` (якорь [§194](https://github.com/arxohq/law/blob/master/spec/SPEC.ru/27-part-xxvi-static-semantics-and-diagnostics.ru.md#194-sourceprovenance-checks) в преамбулу или иной
текст о том, ЗАЧЕМ акт принят). Модуль отвечает на три вопроса тремя
чистыми операциями над уже существующими движками и не содержит ни строчки
семантики (инвариант 5):

- вердикт цели над МНОЖЕСТВОМ миров (дела формата О-1): `HELD`, `FAILED`
  (контрпримеры названы парой мир/сущность), `SKIPPED` (наблюдающее правило
  не исполнено, [§111](https://github.com/arxohq/law/blob/master/spec/SPEC.ru/16-part-xv-defeasible-semantics-and-conflict-resolution.ru.md#111-порядок-evaluation-strata)) и `VACUOUS` — домен пуст во ВСЕХ мирах. Последний —
  третье значение, а не «держится на нуле»: цель по выходу невыбранного
  прочтения вакуумна всегда, и без этого значения фильтр ниже либо всё
  отбрасывает, либо пропускает пустой контекст (замер на fiqh.sawm
  02.09.2026);
- таблица «прочтение × цель» (`--by-interpretation`): по одному контексту
  на альтернативу группы [§155](https://github.com/arxohq/law/blob/master/spec/SPEC.ru/21-part-xx-interpretations-and-theories.ru.md#155-interpretation-group) (`exactly_one` — каждая; `any_of` — пустой
  выбор и каждая порознь; `compose_explicitly` — не перечисляется, назван
  в манифесте). Режим анализа [§156](https://github.com/arxohq/law/blob/master/spec/SPEC.ru/21-part-xx-interpretations-and-theories.ru.md#156-evaluation-of-alternatives) оракулом не реализован, и здесь он не
  нужен: N контекстов — оркестрация;
- телеологический ФИЛЬТР с порядком целей `over`: по рангам от старших к
  младшим остаются альтернативы без единого `FAILED` в ранге, а среди них —
  с хотя бы одним `HELD`, если такие есть. Итог — `TELEOLOGICAL-UNIQUE`,
  `-AMBIGUOUS`, `-VOID` (ни одна не служит целям), `-VACUOUS` (ни одна цель
  ни одну альтернативу не различает). Фильтр НЕ пишет контекст и не
  выбирает: выбор прочтения остаётся за контекстом дела [§152](https://github.com/arxohq/law/blob/master/spec/SPEC.ru/21-part-xx-interpretations-and-theories.ru.md#152-interpretation).

Исполняет свойство оракул (`lawtest.run_property`); понижение свойства —
работа компилятора (`lawc lower-property --all`), и модуль принимает уже
понижённые документы, чтобы не зависеть от него.

## lawref.goals.ALTERNATIVES_CAP

*attribute* · *module attribute*

```python
ALTERNATIVES_CAP = 64
```

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L41-L41)

## lawref.goals.GOALS_BROKEN

*attribute* · *module attribute*

```python
GOALS_BROKEN = 'GOALS-BROKEN'
```

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L279-L279)

## lawref.goals.GOALS_PRESERVED

*attribute* · *module attribute*

```python
GOALS_PRESERVED = 'GOALS-PRESERVED'
```

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L278-L278)

## lawref.goals.GOALS_VACUOUS

*attribute* · *module attribute*

```python
GOALS_VACUOUS = 'GOALS-VACUOUS'
```

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L280-L280)

## lawref.goals.NO_SELECTION

*attribute* · *module attribute*

```python
NO_SELECTION = '—'
```

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L40-L40)

## lawref.goals.SCHEMA_VERSION

*attribute* · *module attribute*

```python
SCHEMA_VERSION = 'law.goals/0.1'
```

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L39-L39)

## lawref.goals.GoalsError

*class*

```python
class GoalsError(ValueError)
```

Bases: `ValueError`

Отказ по входу: цель без основания, повисший якорь, цикл порядка.

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L44-L45)

## lawref.goals.aggregate

*function*

```python
def aggregate(verdicts: list[str]) -> str
```

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L147-L151)

## lawref.goals.alternatives

*function*

```python
def alternatives(ir: dict, cap: int = ALTERNATIVES_CAP) -> tuple[list[dict], list[dict]]
```

Альтернативы прочтений из групп [§155](https://github.com/arxohq/law/blob/master/spec/SPEC.ru/21-part-xx-interpretations-and-theories.ru.md#155-interpretation-group) документа: список
`{"label", "selected": [urn...]}` и список групп манифеста.

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L104-L132)

## lawref.goals.build

*function*

```python
def build(ir: dict, documents: list[dict], worlds: list[tuple[str, dict]], by_interpretation: bool = False) -> dict
```

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L259-L273)

## lawref.goals.check_goals

*function*

```python
def check_goals(ir: dict, documents: list[dict]) -> None
```

Каждая цель несёт `basis`, и он ведёт в фрагмент документа.

Повисший якорь молчалив (`dangling-source-anchor-is-silent`), поэтому
отказ здесь, до единого вызова движка.

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L54-L72)

## lawref.goals.evaluate_goals

*function*

```python
def evaluate_goals(ir: dict, documents: list[dict], worlds: list[tuple[str, dict]], alternatives_list: list[dict] | None = None) -> dict[str, Any]
```

Отчёт: манифест + строки (альтернатива × цель) с вердиктом по мирам.
Детерминирован кортежем (документ, цели, миры, альтернативы): цели и
миры сортируются по имени, чтобы байты не зависели от порядка argv.

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L165-L203)

## lawref.goals.exit_code

*function*

```python
def exit_code(report: dict) -> int
```

0 — цели держатся (или прочтение найдено/не единственно), 1 —
контрпример, 4 — «не утверждение о праве» (вакуум, пропуск, VOID).

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L249-L256)

## lawref.goals.goal_ranks

*function*

```python
def goal_ranks(documents: list[dict]) -> dict[str, int]
```

Ранг цели по порядку `over`: 0 у старших, +1 за каждое ребро вниз
(длиннейший путь). Цикл — отказ: порядок обязан быть частичным.

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L75-L101)

## lawref.goals.impact_section

*function*

```python
def impact_section(before: dict, after: dict, documents: list[dict], worlds: list[tuple[str, dict]]) -> dict
```

Раздел `goals` impact-отчёта: вердикт каждой цели ДО и ПОСЛЕ на одних
мирах, разность контрпримеров, итог.

`GOALS-BROKEN(<цели>)` — цель держалась до и упала после (FAILED) либо
перестала проверяться (SKIPPED); уже павшая до и павшая после названа
отдельно (`alreadyFailed`) — поправка её не ломала. `GOALS-VACUOUS` —
ни одна цель после поправки не имеет домена ни в одном мире: «цели
сохранены» на нуле дел не утверждается. Основания сверяются с
документом ДО; после поправки фрагмент может исчезнуть — это названо
полем `basisAfter`, а не отказом: снятая преамбула сама есть находка.

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L283-L332)

## lawref.goals.plain_verdict

*function*

```python
def plain_verdict(report: dict) -> str
```

Итог без прочтений: FAILED > SKIPPED > VACUOUS > HELD.

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L240-L246)

## lawref.goals.render_impact_section

*function*

```python
def render_impact_section(section: dict) -> list[str]
```

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L335-L352)

## lawref.goals.render_text

*function*

```python
def render_text(report: dict) -> str
```

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L359-L388)

## lawref.goals.report_bytes

*function*

```python
def report_bytes(report: dict) -> bytes
```

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L355-L356)

## lawref.goals.teleological_filter

*function*

```python
def teleological_filter(report: dict) -> dict
```

Лексикографический фильтр по рангам целей (DECISION-0089 [§4.3](https://github.com/arxohq/law/blob/master/spec/SPEC.ru/02-part-ii-goals-and-scope.ru.md#4-не-цели-01)).

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L208-L237)

## lawref.goals.world_verdict

*function*

```python
def world_verdict(result: dict) -> str
```

[View source](https://github.com-arxohq/arxo-io/law/blob/2edc2b92ce22b52e03f4081d2769a58229684379/engines/lawref/lawref/goals.py#L137-L144)