"""出生时间「按用途够用」的用途决策合同(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')