From 80c6cdb7efc29d5335972f4dccc9220d5318b2e7 Mon Sep 17 00:00:00 2001 From: HarcoChen Date: Sat, 14 Nov 2026 15:06:27 +0800 Subject: [PATCH 1/2] Expose public decision settlement feedback --- README.md | 31 +++++++++++++ crates/engine/src/battle/health.rs | 46 +++++++++++++++++++ crates/engine/src/battle/runtime.rs | 8 ++++ crates/engine/src/solo.rs | 24 ++++++++++ crates/engine/src/solo/preparation.rs | 12 +++++ crates/engine/src/solo/preparation/effects.rs | 4 ++ .../src/solo/preparation/effects/dispatch.rs | 18 +++++++- crates/engine/src/solo/session.rs | 22 +++++++-- crates/python/src/ledger.rs | 9 ++++ src/arkguardrl_core/native_batch.py | 3 +- src/arkguardrl_core/native_ledger.py | 5 ++ 11 files changed, 176 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 5aee882..bb82d25 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,37 @@ Linux 动态库为 `lib_native.so`,Windows 使用 CI 的 `_native*.pyd`。[跨 - 自然结束为 `terminated`,预算耗尽为 `truncated`,原因见 `info["reason"]`。相同种子可复现,`reset(seed=None)` 延续 RNG 流。 - Gym 支持 Sync/Async,Rust slots 支持 1–64 个环境及局部重置。Async `spawn` 入口使用 `if __name__ == "__main__"`。 +### 逐决策公开反馈 + +NativeSolo 和 NativeBatch 的 decision ledger JSON 现在包含独立的 `feedback` 字段。 +`NativeLedgerEnv.feedback` 和 Rust slots 的 `info["feedback"]` 返回该侧带记录。 +重置时为 `null`,每次决策替换为 `arkguard.decision-feedback.v1`,包含 +`decisionRevision`、`resultRevision` 和按 transport revision 排列的 `receipts`。 +每个 receipt 使用 `arkguard.public-feedback.v1`,携带 `revision`、`battle`、`economy`。 +反馈由动作及后续自动战斗共同生成,初始设置授予发生在首个决策之前。 + +`battle` 在战斗结算时包含 1 起算 `round`、`units`、`complete`、`partial`、 +`droppedUnits`、`missingMetrics`。每行有局内 `battleUnitId`、准备阶段 `sourceUid`、 +召唤者 `ownerSourceUid`、`ownerAttributionComplete`、`kind`,以及真实累计的 +`damage`、`healing`、`taken`、`attacks`、`kills`。 +`damage` 是异阵营归属伤害,`taken` 是实际 HP 损失,`healing` 是有效治疗量, +`attacks` 使用现有攻击事件计数,`kills` 使用 `deployment.kills` 的直接击杀归属。 +直接击杀计数与出怪 ledger 的 `creditedKills` 有各自口径,召唤物单列,调用方可按 +`ownerSourceUid` 汇总。准备棋子 UID 缺失或召唤者已释放时对应值为 `null`, +归属缺失独立标记。永久移除盟友的最终统计保留,最多 4096 行,超出后 +`droppedUnits > 0`、`partial=true`。完整性描述计数保留情况,技能实现覆盖另行判断。 +当前接口未提供阻挡次数和阻挡时长。 + +`economy.events` 包含 1 起算 `round` 和 `sourceBond`、`effect`。 +`miraShip`/`visiShip` 的层数返金报告实际 `amount` 和入账 `destination` +(`funds` 或 `pendingFunds`),`miraShip` 免费刷新报告已授予次数。 +`investShip` 报告额外驻守调用的 `sourceUid`、`garrisonId`、1 起算 `invocation`, +以及实际 `fundsDelta`、`pendingFundsDelta`、`freeRefreshesDelta`。 +该增量包含调用内嵌套效果,返金事件可能同时描述其中的入账,消费方须避免重复累计。 +物品和层数等非货币结果尚缺归属,故 invest 事件 `complete=false`。 +经济总对象始终标 `complete=false`、`partial=true`,用 `coverage`/`missing` 列明范围。 +单次累积最多保留 4096 个经济事件,截断数见 `droppedEvents`。 + ## 性能 ![同种子同动作购买部署对局,Rust 相对 Node 在三个核心上为 1.32–1.36 倍](docs/assets/benchmark-throughput.svg) diff --git a/crates/engine/src/battle/health.rs b/crates/engine/src/battle/health.rs index 302d44a..68e80cc 100644 --- a/crates/engine/src/battle/health.rs +++ b/crates/engine/src/battle/health.rs @@ -167,6 +167,8 @@ pub struct World { deployment_sequence: u64, attack_sequence: u64, units: BTreeMap, + retired_ally_feedback: Vec, + dropped_ally_feedback: u64, pools: BTreeMap, players: BTreeMap, capacities: [usize; 3], @@ -233,6 +235,8 @@ impl World { deployment_sequence: 0, attack_sequence: 0, units: BTreeMap::new(), + retired_ally_feedback: Vec::new(), + dropped_ally_feedback: 0, pools: BTreeMap::new(), players: BTreeMap::new(), capacities: [unit_capacity, pool_capacity, player_capacity], @@ -290,10 +294,52 @@ impl World { if !u.removed || u.pins > 0 || u.blocked_by.is_some() || !u.blocking.is_empty() { return Err("Cannot release a retained or still linked unit".into()); } + if u.side == Side::Ally { + if self.retired_ally_feedback.len() < 4096 { + let feedback = self.ally_feedback(id)?; + self.retired_ally_feedback.push(feedback); + } else { + self.dropped_ally_feedback += 1; + } + } super::enemy::clear(self, id)?; self.units.remove(&id); Ok(()) } + fn ally_feedback(&self, id: Id) -> Result { + let u = self.unit(id)?; + let source = u.summoner; + let owner_uid = source.and_then(|owner| self.unit(owner).ok()?.deployment.uid); + Ok(serde_json::json!({ + "battleUnitId": id, "sourceUid": u.deployment.uid, + "ownerSourceUid": owner_uid, + "ownerAttributionComplete": source.is_none() || owner_uid.is_some(), + "kind": match u.deployment.kind { + super::deploy::Kind::Operator => "operator", + super::deploy::Kind::Token => "token", + super::deploy::Kind::Device => "device", + super::deploy::Kind::Enemy => "enemy", + }, + "damage": u.damage_dealt, "healing": u.healing_done, + "taken": u.damage_taken, "attacks": u.attacks, + "kills": u.deployment.kills, + })) + } + /// Public measured contributions, including permanently removed allies. + pub(crate) fn contribution_feedback(&self) -> Result { + let mut units = self.retired_ally_feedback.clone(); + for (&id, u) in &self.units { + if u.side == Side::Ally { + units.push(self.ally_feedback(id)?); + } + } + Ok(serde_json::json!({ + "complete": self.dropped_ally_feedback == 0, + "partial": self.dropped_ally_feedback != 0, + "droppedUnits": self.dropped_ally_feedback, + "missingMetrics": [], "units": units, + })) + } pub fn pool(&self, id: Id) -> Option<&Pool> { self.pools.get(&id).map(|p| &p.value) } diff --git a/crates/engine/src/battle/runtime.rs b/crates/engine/src/battle/runtime.rs index 06da896..bbd3c6e 100644 --- a/crates/engine/src/battle/runtime.rs +++ b/crates/engine/src/battle/runtime.rs @@ -814,6 +814,14 @@ impl Field { } /// Owned accounting snapshot. This internal field result is not a policy /// observation and exposes no provisional success for a faulted execution. + /// Settled public event counters only, separate from policy observations. + pub fn contribution_feedback(&self) -> Result { + self.healthy()?; + if !self.finished() { + return Err("Contribution feedback requires completed combat".into()); + } + self.core.world.contribution_feedback() + } pub fn result(&self) -> Result { self.healthy()?; if !self.finished() { diff --git a/crates/engine/src/solo.rs b/crates/engine/src/solo.rs index 57bd625..4a2ccdb 100644 --- a/crates/engine/src/solo.rs +++ b/crates/engine/src/solo.rs @@ -141,6 +141,7 @@ pub struct Runner { rounds_passed: u32, limits: Limits, last_result: Option, + battle_feedback: Option, prep: Option, map: crate::battle::runtime::MapConfig, draft: Option, @@ -294,6 +295,7 @@ impl Runner { rounds_passed: 0, limits, last_result: None, + battle_feedback: None, prep: None, map: Default::default(), draft: None, @@ -715,6 +717,12 @@ impl Runner { Ok(value) => value, Err(error) => return self.fail(error), }; + let mut feedback = match field.contribution_feedback() { + Ok(value) => value, + Err(error) => return self.fail(error), + }; + feedback["round"] = json!(self.index + 1); + self.battle_feedback = Some(feedback); let gains = field.layer_gains(); if let Err(error) = self.settle(result, layers, &gains) { return self.fail(error); @@ -744,6 +752,22 @@ impl Runner { None }) } + pub(in crate::solo) fn take_feedback(&mut self) -> Value { + let economy = self + .prep + .as_mut() + .map(|prep| { + json!({"events": std::mem::take(&mut prep.economy_feedback), + "droppedEvents": std::mem::take(&mut prep.dropped_economy_feedback), + "coverage": ["miraShip.freeRefresh", "miraShip.funds", "visiShip.funds", + "investShip.extraGarrisonInvocation"], + "complete": false, "partial": true, + "missing": ["otherEconomicEffects", "investShip.nonCurrencyOutcomes"]}) + }) + .unwrap_or(Value::Null); + json!({"schema": "arkguard.public-feedback.v1", + "battle": self.battle_feedback.take(), "economy": economy}) + } pub fn last_result(&self) -> Result, String> { self.healthy()?; Ok(self.last_result) diff --git a/crates/engine/src/solo/preparation.rs b/crates/engine/src/solo/preparation.rs index b668073..6c6e722 100644 --- a/crates/engine/src/solo/preparation.rs +++ b/crates/engine/src/solo/preparation.rs @@ -187,6 +187,8 @@ pub(super) struct Preparation { bounties: Vec, meta: Option, free_refreshes: u64, + pub(in crate::solo) economy_feedback: Vec, + pub(in crate::solo) dropped_economy_feedback: u64, grid: Arc, boss: bool, deploy_cap: usize, @@ -286,6 +288,8 @@ impl Preparation { rules, meta, free_refreshes: 0, + economy_feedback: Vec::new(), + dropped_economy_feedback: 0, grid: Arc::new(grid), boss, deploy_cap, @@ -316,6 +320,14 @@ impl Preparation { } Ok(prep) } + fn record_economy_feedback(&mut self, mut event: Value) { + event["round"] = json!(self.meta.as_ref().map(|meta| meta.round)); + if self.economy_feedback.len() < 4096 { + self.economy_feedback.push(event); + } else { + self.dropped_economy_feedback += 1; + } + } pub fn begin_round( &mut self, round: u32, diff --git a/crates/engine/src/solo/preparation/effects.rs b/crates/engine/src/solo/preparation/effects.rs index 532057b..259b5c1 100644 --- a/crates/engine/src/solo/preparation/effects.rs +++ b/crates/engine/src/solo/preparation/effects.rs @@ -863,6 +863,10 @@ impl Preparation { .earn(gain.trunc() as u64) .map_err(|_| Error::Capacity)?; } + self.record_economy_feedback(json!({"sourceBond": id, + "effect": "bond_layer_gain_coin", "amount": gain.trunc() as u64, + "destination": if pending { "pendingFunds" } else { "funds" }, + "complete": true})); } } if id == "visiShip" { diff --git a/crates/engine/src/solo/preparation/effects/dispatch.rs b/crates/engine/src/solo/preparation/effects/dispatch.rs index 298e27d..c40a55c 100644 --- a/crates/engine/src/solo/preparation/effects/dispatch.rs +++ b/crates/engine/src/solo/preparation/effects/dispatch.rs @@ -176,8 +176,21 @@ impl Preparation { } } } - for _ in 0..self.gain_repeat(hook)? { + for invocation in 0..self.gain_repeat(hook)? { + let before = (player.funds, player.pending, self.free_refreshes); self.run_rule(&rule, &call, player)?; + if invocation > 0 { + self.record_economy_feedback(json!({ + "sourceBond": "investShip", "effect": "extraGarrisonInvocation", + "sourceUid": call.piece.uid, "garrisonId": id, + "invocation": invocation + 1, + "fundsDelta": player.funds as i64 - before.0 as i64, + "pendingFundsDelta": player.pending as i64 - before.1 as i64, + "freeRefreshesDelta": self.free_refreshes as i64 - before.2 as i64, + "complete": false, + "missing": ["nonCurrencyOutcomes"], + })); + } } } Ok(()) @@ -352,6 +365,9 @@ impl Preparation { if self.meta.as_mut().unwrap().rng.next_f64() < chance { self.free_refreshes = add(self.free_refreshes, 1).map_err(|_| Error::Capacity)?; + self.record_economy_feedback(json!({"sourceBond": "miraShip", + "effect": "bond_refresh_shop_next_free", "amount": 1, + "destination": "freeRefreshes", "complete": true})); } } } diff --git a/crates/engine/src/solo/session.rs b/crates/engine/src/solo/session.rs index 686e640..0c212a6 100644 --- a/crates/engine/src/solo/session.rs +++ b/crates/engine/src/solo/session.rs @@ -42,7 +42,9 @@ impl Session { session.public_setup = public_setup; Ok(session) } - pub(in crate::solo) fn from_runner(run: Runner) -> Self { + pub(in crate::solo) fn from_runner(mut run: Runner) -> Self { + // Setup grants precede the first decision and are not action outcomes. + run.take_feedback(); Self { run, revision: 0, @@ -122,6 +124,18 @@ impl Session { "accepted": accepted, "rejection": rejection, "ticks": ticks, })) } + fn feedback_receipt( + &mut self, + accepted: Option, + rejection: Option<&str>, + ticks: usize, + ) -> Result { + let mut receipt = self.receipt(accepted, rejection, ticks)?; + let mut feedback = self.run.take_feedback(); + feedback["revision"] = json!(self.revision); + receipt["feedback"] = feedback; + Ok(receipt) + } pub fn status(&self) -> Result { self.healthy()?; self.receipt(None, None, 0) @@ -161,7 +175,7 @@ impl Session { match result { Err(error) if self.run.phase() != Phase::Faulted && is_rejection(&error) => { self.revision += 1; - self.receipt(Some(false), Some(&error), 0) + self.feedback_receipt(Some(false), Some(&error), 0) } Err(error) => self.fail(error), Ok(()) => { @@ -170,7 +184,7 @@ impl Session { Ok(a) => a, Err(error) => return self.fail(error), }; - self.receipt(Some(true), None, advance.ticks) + self.feedback_receipt(Some(true), None, advance.ticks) } } } @@ -185,7 +199,7 @@ impl Session { Err(error) => return self.fail(error), }; self.revision += 1; - self.receipt(None, None, advance.ticks) + self.feedback_receipt(None, None, advance.ticks) } } fn is_rejection(error: &str) -> bool { diff --git a/crates/python/src/ledger.rs b/crates/python/src/ledger.rs index 3c1107a..c96512f 100644 --- a/crates/python/src/ledger.rs +++ b/crates/python/src/ledger.rs @@ -14,6 +14,7 @@ pub struct DecisionLedger { pub blocked: BTreeSet, progress: PublicProgress, reward: NativeProgressCore, + feedback: Value, } impl DecisionLedger { @@ -31,6 +32,7 @@ impl DecisionLedger { blocked: BTreeSet::new(), progress, reward, + feedback: Value::Null, }) } @@ -45,6 +47,7 @@ impl DecisionLedger { #[derive(serde::Serialize)] struct Snapshot<'a> { observation: &'a Value, + feedback: &'a Value, history: &'a Value, blocked: &'a BTreeSet, execution: Option, @@ -53,6 +56,7 @@ impl DecisionLedger { } serde_json::to_string(&Snapshot { observation: &self.state, + feedback: &self.feedback, history: &self.policy_history, blocked: &self.blocked, execution, @@ -72,6 +76,7 @@ impl DecisionLedger { let before = Arc::clone(&self.state); // Preserve the immediate receipt before advancing the resulting battle. let mut transport = session.step(action, 0)?; + let mut receipts = vec![transport["feedback"].clone()]; let accepted = transport["accepted"] .as_bool() .ok_or("Missing action acceptance")?; @@ -91,6 +96,7 @@ impl DecisionLedger { return Err("Combat budget exhausted before a decision boundary".into()); } transport = session.advance(tick_budget)?; + receipts.push(transport["feedback"].clone()); advances += 1; if transport["budgetExhausted"] != true { after = Arc::new(session.observation()?); @@ -107,6 +113,9 @@ impl DecisionLedger { accepted, )?; let reward = self.reward.step(&before, &after)?; + self.feedback = json!({"schema": "arkguard.decision-feedback.v1", + "decisionRevision": before["revision"], "resultRevision": after["revision"], + "receipts": receipts}); self.state = after; self.snapshot(Some(execution), Some(reward), advances) } diff --git a/src/arkguardrl_core/native_batch.py b/src/arkguardrl_core/native_batch.py index 2bd80e4..3c0979b 100644 --- a/src/arkguardrl_core/native_batch.py +++ b/src/arkguardrl_core/native_batch.py @@ -98,7 +98,8 @@ def _refresh(self, slot): slot.decision = None slot.info = dict(candidate_count=0, phase=slot.state['phase'], round=slot.state['round'], - engine_seed=slot.engine_seed, reason=slot.reason or '') + engine_seed=slot.engine_seed, reason=slot.reason or '', + feedback=deepcopy(slot._ledger.get('feedback'))) def _output(self): n, k = self.num_envs, self.max_candidates diff --git a/src/arkguardrl_core/native_ledger.py b/src/arkguardrl_core/native_ledger.py index e85ff92..b0c4fd4 100644 --- a/src/arkguardrl_core/native_ledger.py +++ b/src/arkguardrl_core/native_ledger.py @@ -130,6 +130,11 @@ def _encode_numeric(self, state, actions, catalog, history): raise ValueError('Numeric encoding requires the current public snapshot and catalog') return encode(self.session, state, actions, history, native_history=True) + @property + def feedback(self): + """Public measured outcomes from the most recent native decision.""" + return deepcopy(getattr(self, '_ledger', {}).get('feedback')) + def _consume(self, raw): ledger = json.loads(raw) state = ledger['observation'] From 70f817d83d3f8c79d409cf1f0d5a9e8a89f1a93e Mon Sep 17 00:00:00 2001 From: HarcoChen Date: Sat, 14 Nov 2026 15:07:43 +0800 Subject: [PATCH 2/2] Clarify retired contribution record bound --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index bb82d25..ddd0166 100644 --- a/README.md +++ b/README.md @@ -88,8 +88,9 @@ NativeSolo 和 NativeBatch 的 decision ledger JSON 现在包含独立的 `feedb `attacks` 使用现有攻击事件计数,`kills` 使用 `deployment.kills` 的直接击杀归属。 直接击杀计数与出怪 ledger 的 `creditedKills` 有各自口径,召唤物单列,调用方可按 `ownerSourceUid` 汇总。准备棋子 UID 缺失或召唤者已释放时对应值为 `null`, -归属缺失独立标记。永久移除盟友的最终统计保留,最多 4096 行,超出后 -`droppedUnits > 0`、`partial=true`。完整性描述计数保留情况,技能实现覆盖另行判断。 +归属缺失独立标记。最多保留 4096 条已移除盟友的最终统计,另加入结算时仍在 +注册表中的盟友(受现有 unit 容量约束)。移除记录超出后 `droppedUnits > 0`、 +`partial=true`。完整性描述计数保留情况,技能实现覆盖另行判断。 当前接口未提供阻挡次数和阻挡时长。 `economy.events` 包含 1 起算 `round` 和 `sourceBond`、`effect`。