feat(miracle): 明确定义策略状态与正式 IG 合同

docs/games/24_miracle_decision_space_kl.v2.md

@@ -0,0 +1,82 @@
+# 24_miracle Decision Space + policy-KL Core v2
+
+Authority: [24_miracle policy information-gain contract](24_miracle_kl_contract_authority.v2.md).
+
+## Scope
+
+The core is a pure, synthetic/fake-only calculator. It never runs a policy,
+Judge, environment, opponent, provider, match or session, and does not claim
+real old/new policy provenance or authoritative readiness.
+
+One Miracle decision is one legal atomic Judge operation at a target-agent
+pre-action observation. Public families are `init`, `move`, `attack`,
+`summon`, `use`, `endround` and `surrender`. Parser-internal operations are not
+decisions. The complete support is rebuilt from the observation, canonicalized,
+assigned stable action IDs, sorted and bound to `support_id`. WindBlessing
+continues to fail closed where its authoritative position support cannot be
+finitely enumerated.
+
+## Strict evidence boundary
+
+`DecisionKLEvidence` contains only:
+
+- continuous `decision_step`;
+- frozen `state_before`;
+- frozen complete support identity;
+- complete old and new action-ID probability mappings.
+
+Nested caller-owned data is copied and frozen. The calculator regenerates the
+support, checks schema/support/action order, rejects missing or extra actions,
+rejects bool/string/NaN/Infinity/negative probabilities, and requires unit
+mass without normalization or implicit zero filling. A submitted local KL or
+summary is not accepted as input.
+
+Issuer-only decision records and summaries are bound to closure-owned snapshots.
+Construction, copying, replacement or post-issue mutation cannot be reused as
+trusted aggregation evidence. Expected support/distribution unavailability is
+represented as a structured `incomplete` record with a null scalar. API type,
+identity and ordering violations fail closed.
+
+## Formal calculation
+
+For complete current support `A(s)` and fixed `epsilon=0.01`:
+
+```text
+pi_epsilon(a|s) = 0.99 * pi(a|s) + 0.01 / |A(s)|
+
+local_policy_kl(s)
+  = sum_a new_epsilon(a|s) * ln(new_epsilon(a|s) / old_epsilon(a|s))
+```
+
+The logarithm is natural. Both policies use the same support and identical
+smoothing channel. Equal deterministic actions produce zero; changed
+deterministic actions produce a finite positive value. Epsilon affects the
+measurement only and never the executed policy.
+
+The summary retains ordered `decision_records` and `trace`. For a complete,
+non-empty trace:
+
+```text
+information_gain = trajectory_kl = arithmetic_mean(trace)
+sum_local_kl = sum(trace)
+```
+
+`information_gain`/`trajectory_kl` use `nats / decision`; `sum_local_kl` uses
+`nats / episode`. Maximum and percentiles remain diagnostics. There is no
+policy-change acceptance threshold; the deprecated compatibility fields
+`acceptance_threshold` and `threshold_passed` are always null. Empty or partly
+incomplete traces never expose an episode scalar.
+
+Every machine-readable summary remains labeled
+`evidence_scope=synthetic_fake_only`, `authoritative_readiness=false`,
+`verified_rollout_source=null` and `policy_binding_verified=false`.
+`rollout_source_contract=new_policy` states the target contract only; it does
+not turn synthetic states into verified occupancy evidence.
+
+## Remaining real-evidence gap
+
+The current synthetic input records visible state only. If a real HL policy is
+stateful, authoritative comparison requires canonical `z=(s,m)` evidence.
+Until internal memory `m` is captured and bound, real stateful policy KL is
+incomplete even when visible-state support and distributions are otherwise
+valid.

docs/games/24_miracle_ifelse_policy_state.v1.md

@@ -0,0 +1,122 @@
+# 24_miracle explicit if-else policy state v1
+
+Status: **local deterministic adapter candidate; H08 v2 regeneration still
+required**.
+
+This adapter closes the implementation gap between the stateful legacy
+`IfElseAI.play()` control flow and the policy-information-gain contract. It
+does not approve a replay, change an allowlist, or turn historical post-hoc
+data into formal experiment evidence.
+
+## Decision boundary
+
+One decision is one atomic Judge operation. `summon`, `move`, `attack`, and
+`use` send an operation and then read a fresh Judge observation before the
+legacy Python function continues. A single `play()` can therefore adaptively
+emit artifact, repeated pre-move attacks, moves, post-move attacks, summons,
+and end-round operations. The complete turn-level command sequence is not a
+finite action known at turn start, so a turn-level macro-action cannot supply
+the required complete canonical `A(s)`.
+
+The formal comparison context is consequently `z=(s,m)`, where `s` is the
+pre-operation observation and `m` is `PolicyMemoryV1`.
+
+## Frozen policy identity
+
+The policy identity binds:
+
+```text
+verified six-file source identity
++ canonical 62-input configuration identity
++ 24-miracle-ifelse-explicit-state-machine-v1
++ provider version
+```
+
+The 62 inputs are 59 strict booleans plus `MIRACLE_CAMP1_OPENING`,
+`MIRACLE_ARTIFACT`, and `MIRACLE_DECK`. Opening is one of `FF/SF/IF`;
+artifact and creature names must be members of the Judge `Data.json`
+enumerations. An explicit configuration must contain all 62 inputs. A
+historical unknown is retained as the literal `unknown` and makes formal
+provider construction incomplete.
+
+The source reader binds `Data.json`, `ai_client.py`, `calculator.py`,
+`card.py`, `gameunit.py`, and `main.py`; all must be non-empty strict UTF-8,
+BOM-free regular files. It revalidates the source before every selection and
+loads with bytecode writes disabled.
+
+## Serializable memory
+
+`PolicyMemoryV1` contains only canonical serializable values:
+
+```text
+schema_version, state_machine_version
+policy_identity, policy_config_identity
+episode_id, decision_step, lifecycle
+phase, instruction_label, attack_pass, preserve_for_move, acted_iteration
+ordered_unit_ids, ordered_unit_snapshots, current_unit_cursor
+ordered_target_ids, current_target_cursor
+ordered_positions, position_cursor
+remaining_capacities, local_mana, local_unit_counts
+camp, rng_mode, rng_state, previous_transition_sha256
+```
+
+The move-phase snapshots are necessary because legacy `move_phase()` freezes
+its sorted unit-object iteration at phase entry. Recomputing that order from a
+later observation changes behavior. No Python frame, iterator, policy object,
+address, file handle, clock, environment lookup, or RNG object is retained.
+The only supported RNG identity is `rng_mode=none`, `rng_state=null`.
+
+Memory and pair-decision evidence are issuer-bound immutable snapshots. Every
+episode starts from one explicit reset state. The machine keeps an issuer-side
+transition tip only to reject replayed, skipped, or spliced evidence; all
+policy decision state remains serialized in `m`. Old and new providers are
+recomputed on the same exact `m_before`, observation, and regenerated complete
+ActionSupport. They return unsmoothed one-hot base distributions. Epsilon
+regularization belongs exclusively to the formal IG measurement layer.
+
+## Local replay evidence
+
+The H08 trace with SHA-256
+`e0e280338ae3b06818a923733fb4a04a3730d931ea800e144ecd0aadf4241948`
+was replayed sequentially from one reset under an explicit all-false/default
+configuration assumption:
+
+```text
+399 / 399 chosen operations reproduced
+399 / 399 complete ActionSupport values rebuilt
+399 / 399 recorded operations were in support
+399 / 399 old/new evaluations shared m_before
+```
+
+The trace exercised init, opening, artifact, repeated pre-move attack, move,
+post-move attack, summon, and endround behavior; the longest consecutive attack
+run was five operations.
+
+All eight retained historical v0/v1 traces also replayed completely for both
+camps and rank04/rank09 when evaluated under explicit default assumptions. The
+observed action counts were 403, 621, 342, and 375 for each version. This is a
+behavior-equivalence diagnostic only: those sessions did not record all 62
+environment values, so their configuration evidence remains unknown and
+cannot be promoted to formal IG evidence.
+
+The verified H08/v0 source has canonical tree SHA-256
+`c27a8b646e57b902f527061b4f041b24e000420c7e9bfeacd9d7563ab0de7254`,
+legacy tree SHA-256
+`209f182637e1abaee4ff50de6b1a37777fbba9fbab5f611aae58a06a109c0a3b`,
+and full `main.py` SHA-256
+`98199fae8875de63b41d2eacd92ad5c58b4d5aa95b01b05aeacedd0b55402f4b`.
+The shorter value ending in `...402f4` is not a valid SHA-256.
+
+A deterministic v0/v1 diagnostic on the fixed camp-0 H08 episode used
+different provider identities and explicit FF/SF configurations. Both chose
+the same 399 operations, so the ordered fixed-epsilon trace contained 399
+zeros, with mean `0.0 nats / decision` and sum `0.0 nats / episode`. This is
+not a formal curve or performance result.
+
+## Remaining gate
+
+`CURRENT_INTERNAL_MEMORY_EVIDENCE` remains `not_collected`. A new H08 v2 run
+must explicitly record all 62 configuration values and their canonical digest,
+the verified source/provider identities, `m_before` and transition evidence at
+every decision, and the actual new-policy rollout identity. Only that new
+evidence can bind `internal_memory_evidence` and permit a formal IG preflight.

docs/games/24_miracle_kl_contract_authority.v2.md

@@ -0,0 +1,105 @@
+# 24_miracle policy information-gain contract authority v2
+
+Status: **measurement contract migrated locally; authoritative execution remains blocked**.
+
+This document records the group-approved scientific definition for 24_miracle.
+It governs measurement semantics, not production approval, real replay status,
+benchmark completion, or permission to start an experiment.
+
+## Fixed scientific identity
+
+```text
+ACTION_BOUNDARY = one legal atomic Judge operation
+SUPPORT = same complete canonical state-local ActionSupport A(s)
+KL_DIRECTION = new||old
+LOGARITHM = natural
+SMOOTHING = symmetric epsilon mixture with uniform(A(s))
+MAIN_EPSILON = 0.01
+SENSITIVITY_EPSILONS = 0.001, 0.01, 0.05
+OCCUPANCY_SOURCE = actual new-policy rollout
+PRIMARY_EPISODE_AGGREGATE = arithmetic mean
+PRIMARY_UNIT = nats / decision
+OPTIONAL_SUM_UNIT = nats / episode
+TERMINAL_STATE_INCLUDED = false
+```
+
+For `v_{k-1} -> v_k`, at each actual target-agent decision context `z_t`:
+
+```text
+pi_epsilon(a|z_t) = (1-epsilon) * pi(a|z_t) + epsilon / |A(s_t)|
+
+local_policy_kl_k(z_t)
+  = KL(pi_k,epsilon(.|z_t) || pi_k-1,epsilon(.|z_t))
+```
+
+The same epsilon and the same ordered, complete support are used for both
+policies. Smoothing is a measurement layer only; it never changes the action
+executed by the new policy. The main result always uses epsilon `0.01`.
+Sensitivity values use the fixed panel above and cannot replace or relabel the
+main result.
+
+Each episode retains the ordered source trace:
+
+```text
+local_policy_kl_trace = [k_0, ..., k_(T-1)]
+information_gain = mean(local_policy_kl_trace)       # nats / decision
+local_policy_kl_sum = sum(local_policy_kl_trace)     # nats / episode
+```
+
+The terminal state is excluded because it produces no action. Empty or
+incomplete evidence produces `null/incomplete`, never zero. There is no KL
+magnitude acceptance threshold: epsilon `0.01` is not a performance gate, and
+large policy change does not imply score improvement.
+
+## Action and probability boundary
+
+For Miracle, the action-mask concept is a state-local, complete, ordered and
+verifiable `ActionSupport + support_id`, not a fixed global Boolean vector.
+The support is regenerated from the visible observation where the synthetic
+core can do so. Old/new action IDs must match it exactly. Missing, extra,
+duplicated or drifted identities fail closed.
+
+Probabilities must be exact numeric values (`int` or `float`, never `bool` or
+strings), finite, non-negative and unit mass. The framework does not normalize,
+zero-fill or coerce submitted distributions. Uploaded local KL, trace summary,
+episode mean or sum is never authoritative: validators recompute the values
+from the ordered distributions and reject disagreement.
+
+## Occupancy and interpretation
+
+`occupancy_shift` is an independent measurement of state visitation change.
+It is never added to local policy KL or episode information gain. Policy KL is
+behavioral/policy information gain, not epistemic information gain and not a
+performance score. Performance remains governed by the frozen evaluation
+win-rate/Elo contract.
+
+The occupancy source for the main episode measure is the actual rollout of the
+unsmoothed new policy. Consequently the saved local trace is an
+epsilon-regularized policy-change measurement under new-policy occupancy; the
+optional sum is not presented as a third independent KL.
+
+## Decision context and current data gap
+
+If action choice depends on internal memory, the decision context is
+`z=(s,m)`. The current Miracle adapters can advance stateful callbacks through
+`reset()` and `observe_transition()`, but the evidence record only proves the
+visible observation/state identity. It does not yet serialize a canonical
+policy-memory identity. A stateful real run therefore has an explicit
+`internal_memory_evidence=not_collected` gap and cannot claim authoritative
+policy KL until that evidence is supplied. Stateless fake tests do not close
+this real-data gap.
+
+## Security and lifecycle boundary
+
+The migration preserves support completeness, chosen-in-support checks,
+ordered decision records, strict probability validation, immutable evidence
+snapshots, issuer/provenance checks, replay/path safety, revocation checks and
+lifecycle revalidation. Evaluation-case `information_gain` must equal the mean
+derived from its authoritative ordered trajectory evidence. Acceptance derives
+its aggregate from those validated per-case means rather than self-reported
+case fields.
+
+Production approval tables remain empty. The bootstrap file and approved
+bootstrap SHA are unchanged. Historical v0/v1 data remains `information_gain =
+null` because it excluded replay, decision trace, complete action support and
+old/new policy distributions; no formal IG can be reconstructed from it.