169 lines
7.9 KiB
Python
169 lines
7.9 KiB
Python
"""出生时间「按用途够用」的用途决策合同(BUG-1833,#186 第一步)。
|
||
|
||
移植自占星师 2026-11-09 的参考决策器
|
||
(``docs/tasks/assets/purpose-gate-20261109/reference_gate.py``):
|
||
没有区间宽度门槛,也没有分数差门槛——这是参考代码刻意为之。
|
||
|
||
本模块只回答「这个已经算好的评估,可以在什么范围内被当作够用」,
|
||
不做任何计算、不改出生记录、不证明调用方给的证据为真:
|
||
|
||
- ``can_use_interval`` 只有 ``scope_ready`` 才为真;
|
||
- ``can_modify_birth_record`` 与 ``representative_is_birth_truth`` 永远为假。
|
||
|
||
**尚未接入**:本单只交付合同与测试,没有任何生产入口读它,
|
||
``scope_ready`` 也不会影响任何现有流程。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from typing import Any, Dict, Final, List, Mapping, Sequence, Tuple
|
||
|
||
PURPOSE_USE_SCHEMA: Final[str] = 'jyotish.purpose_use_decision.v1'
|
||
LEGACY_POLICY_VERSION = 'purpose_policy_v1'
|
||
POLICY_VERSION = 'purpose_policy_v2'
|
||
|
||
BINDING_KEYS: Final[Tuple[str, ...]] = (
|
||
'input_revision', 'candidate_set_fingerprint', 'purpose_fingerprint',
|
||
'profile_fingerprint', 'engine_version', 'precision_policy_version',
|
||
'forecast_window_fingerprint',
|
||
)
|
||
|
||
LAYER_COVERAGE_STATES: Final[Tuple[str, ...]] = ('executed_complete', 'partial', 'blocked')
|
||
SCAN_STATES: Final[Tuple[str, ...]] = ('policy_covered', 'sampled_only', 'incomplete')
|
||
BRANCH_STATES: Final[Tuple[str, ...]] = (
|
||
'resolved', 'bounded_equivalent', 'unresolved_material', 'not_evaluated',
|
||
)
|
||
|
||
STATUS_SCOPE_READY: Final[str] = 'scope_ready'
|
||
STATUS_CONDITIONAL: Final[str] = 'conditional'
|
||
STATUS_NEEDS_REFINEMENT: Final[str] = 'needs_refinement'
|
||
STATUS_INSUFFICIENT_EVIDENCE: Final[str] = 'insufficient_evidence'
|
||
STATUS_STALE: Final[str] = 'stale'
|
||
STATUS_NEEDS_INPUT: Final[str] = 'needs_input'
|
||
GROUP_STATUS_ORDER = (
|
||
STATUS_SCOPE_READY, STATUS_CONDITIONAL, STATUS_NEEDS_REFINEMENT,
|
||
STATUS_NEEDS_INPUT, STATUS_INSUFFICIENT_EVIDENCE,
|
||
)
|
||
|
||
|
||
def _binding_is_complete(binding: Any) -> bool:
|
||
return isinstance(binding, dict) and all(
|
||
isinstance(binding.get(key), str) and binding[key] for key in BINDING_KEYS
|
||
)
|
||
|
||
|
||
def _claim_ids(assessment: Mapping[str, Any], field: str) -> List[str]:
|
||
values = assessment.get(field)
|
||
if not isinstance(values, list) or any(not isinstance(value, str) or not value for value in values):
|
||
raise ValueError(f'invalid {field}')
|
||
if len(set(values)) != len(values):
|
||
raise ValueError(f'duplicate {field}')
|
||
return list(values)
|
||
|
||
|
||
def _validate_assessment(assessment: Mapping[str, Any]) -> None:
|
||
"""校验绑定一致的评估内容,字段不合法时抛出 ValueError。"""
|
||
required = assessment.get('required_layers')
|
||
coverage = assessment.get('layer_coverage')
|
||
if (not isinstance(required, list) or not required
|
||
or any(not isinstance(layer, str) or not layer for layer in required)
|
||
or len(set(required)) != len(required)
|
||
or not isinstance(coverage, dict)):
|
||
raise ValueError('explicit nonempty required layer set required')
|
||
if any(coverage.get(layer) not in LAYER_COVERAGE_STATES for layer in required):
|
||
raise ValueError('required layers cannot be absent or not_applicable')
|
||
if assessment.get('scan_state') not in SCAN_STATES:
|
||
raise ValueError('invalid scan_state')
|
||
if assessment.get('branch_state') not in BRANCH_STATES:
|
||
raise ValueError('invalid branch_state')
|
||
for flag in ('domain_complete', 'material_change'):
|
||
if type(assessment.get(flag)) is not bool: # noqa: E721 - 只认真正的 bool,不认 0/1
|
||
raise ValueError(f'{flag} must be a boolean')
|
||
_claim_ids(assessment, 'stable_claim_ids')
|
||
_claim_ids(assessment, 'conditional_claim_ids')
|
||
if set(assessment['stable_claim_ids']) & set(assessment['conditional_claim_ids']):
|
||
raise ValueError('one fact cannot be both stable and conditional')
|
||
|
||
|
||
def _result(status: str, stable: Sequence[str], conditional: Sequence[str], reason: str) -> Dict[str, Any]:
|
||
allowed = list(dict.fromkeys(list(stable) + list(conditional)))
|
||
return {
|
||
'schema': PURPOSE_USE_SCHEMA,
|
||
'status': status,
|
||
'can_use_interval': status == STATUS_SCOPE_READY,
|
||
'can_continue_analysis': bool(allowed),
|
||
'can_modify_birth_record': False,
|
||
'representative_is_birth_truth': False,
|
||
'stable_claim_ids': list(stable),
|
||
'conditional_claim_ids': list(conditional),
|
||
'allowed_claim_ids': allowed,
|
||
'reason': reason,
|
||
}
|
||
|
||
|
||
def _group_result(assessment: dict, stable, conditional) -> dict:
|
||
groups = assessment.get("claim_groups")
|
||
unmapped = assessment.get("unmapped_route_layers")
|
||
missing = assessment.get("missing_domains")
|
||
if not isinstance(groups, list) or not isinstance(unmapped, list) or not isinstance(missing, list):
|
||
raise ValueError("v2 requires explicit claim groups and route coverage")
|
||
ids = set()
|
||
statuses = []
|
||
for group in groups:
|
||
if not isinstance(group, dict):
|
||
raise ValueError("invalid claim group")
|
||
group_id, status = group.get("group_id"), group.get("status")
|
||
if (not isinstance(group_id, str) or not group_id or group_id in ids
|
||
or status not in GROUP_STATUS_ORDER or not isinstance(group.get("layers"), list)
|
||
or not isinstance(group.get("limited_by"), list)):
|
||
raise ValueError("invalid claim group")
|
||
ids.add(group_id)
|
||
statuses.append(status)
|
||
if unmapped or missing:
|
||
statuses.append(STATUS_CONDITIONAL if groups else STATUS_INSUFFICIENT_EVIDENCE)
|
||
status = max(statuses, key=GROUP_STATUS_ORDER.index, default=STATUS_INSUFFICIENT_EVIDENCE)
|
||
reason = {
|
||
STATUS_SCOPE_READY: "adequate_for_frozen_purpose",
|
||
STATUS_CONDITIONAL: "only_listed_claim_groups_are_available",
|
||
STATUS_NEEDS_REFINEMENT: "material_output_change",
|
||
STATUS_NEEDS_INPUT: "purpose_input_required",
|
||
STATUS_INSUFFICIENT_EVIDENCE: "incomplete_claim_group_evidence",
|
||
}[status]
|
||
return {**_result(status, stable, conditional, reason),
|
||
"claim_groups": groups, "unmapped_route_layers": unmapped, "missing_domains": missing}
|
||
|
||
|
||
def assess_use(assessment: dict, expected_binding: dict) -> dict:
|
||
"""Return permissions for the evaluated scope, not birth-time confidence.
|
||
|
||
Deliberately has no interval-width or score-margin threshold.
|
||
stable_claim_ids must cover the entire remaining candidate domain;
|
||
conditional_claim_ids must point to explicit branch/limitation evidence.
|
||
"""
|
||
binding = assessment.get('binding')
|
||
for candidate in (binding, expected_binding):
|
||
if not _binding_is_complete(candidate):
|
||
raise ValueError('complete server binding required')
|
||
if any(binding[key] != expected_binding[key] for key in BINDING_KEYS):
|
||
return _result(STATUS_STALE, [], [], 'binding_changed_recompute')
|
||
|
||
_validate_assessment(assessment)
|
||
required = assessment['required_layers']
|
||
coverage = assessment['layer_coverage']
|
||
stable = assessment['stable_claim_ids']
|
||
conditional = assessment['conditional_claim_ids']
|
||
if binding['precision_policy_version'].startswith(f'{POLICY_VERSION}:'):
|
||
return _group_result(assessment, stable, conditional)
|
||
|
||
if assessment['material_change']:
|
||
return _result(STATUS_NEEDS_REFINEMENT, stable, conditional, 'material_output_change')
|
||
complete = all(coverage[layer] == 'executed_complete' for layer in required)
|
||
if (complete and assessment['domain_complete']
|
||
and assessment['scan_state'] == 'policy_covered'
|
||
and assessment['branch_state'] in ('resolved', 'bounded_equivalent')
|
||
and stable and not conditional):
|
||
return _result(STATUS_SCOPE_READY, stable, [], 'adequate_for_frozen_purpose')
|
||
if stable or conditional:
|
||
return _result(STATUS_CONDITIONAL, stable, conditional, 'only_listed_claims_are_available')
|
||
return _result(STATUS_INSUFFICIENT_EVIDENCE, [], [], 'no_supported_outputs_for_purpose')
|