don
/
neon-sprawl
mirror of https://github.com/ViPro-Technologies/neon-sprawl
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

NEO-152: Address code review doc and alignment register nits. 

Add NEO-152 plan link to alignment footer; reconcile plan with
method-level CompensatingRevertAll anchor; strike review suggestions.
pull/194/head
VinPropane 2026-06-28 12:46:32 -04:00
parent f665841ba2
commit d96a83b6ef
3 changed files with 19 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/decomposition/modules/documentation_and_implementation_alignment.md
View File

File diff suppressed because one or more lines are too long

24
docs/plans/NEO-152-implementation-plan.md
View File

@ -23,7 +23,7 @@ Anchor future E9.M1 catalog events **`contract_issued`**, **`contract_complete`*
| **`contract_issued` anchor** | **`ContractGeneratorOperations.TryIssue`** — after successful **`TryCreateActive`** (first-time active row persisted) | Backlog E7M4-09; NEO-147 deferred hook |
| **`contract_complete` anchor** | **`ContractCompletionOperations.TryCompleteOnEncounterClear`** — after successful **`TryMarkComplete`** + outcome append (delivery already succeeded) | Backlog E7M4-09; partial comment landed in NEO-149 — complete to NEO-121 block style |
| **`reward_anomaly` — economy deny** | **`ContractGeneratorOperations.TryIssue`** when **`ContractEconomyValidation.TryValidateTemplate`** returns false (`economy_cap_exceeded`, `invalid_reward_bundle`) | Backlog E7M4-09; NEO-150 deferred |
| **`reward_anomaly` — delivery rollback** | **`RewardRouterOperations.TryDeliverBundle`** at **`CompensatingRevertAll`** invocations (partial grant apply then revert); E9.M1 filters by **`SourceKind`** (`contract_completion` vs `quest_completion`) | Shared router core (NEO-148); rollback site is private bundle path, not HTTP |
| **`reward_anomaly` — delivery rollback** | Private **`CompensatingRevertAll`** in **`RewardRouterOperations`** (single method-level stub — all **`TryDeliverBundle`** rollback call sites); E9.M1 filters by **`SourceKind`** | Shared router core (NEO-148); DRY vs per-call-site duplicates (NEO-121 central **`Deny`** precedent) |
| **API-layer hooks** | **None** — **`ContractIssueApi`** / **`ContractListApi`** delegate to ops only | NEO-121/141 engine-only precedent |
| **`reward_delivery` for contracts** | **No duplicate** — reuse NEO-130 **`reward_delivery`** hook at **`TryRecord`** success inside shared **`TryDeliverBundle`**; README cross-links contract **`SourceKind`** | NEO-130 already documents payload; contract uses same hook site |
| **Manual QA doc** | **None** — comment-only server story; `dotnet test` covers regression | NEO-141 precedent; no user-visible behavior |
@ -55,20 +55,20 @@ Anchor future E9.M1 catalog events **`contract_issued`**, **`contract_complete`*
- **`ContractGeneratorOperations.TryIssue`:** **`contract_issued`** hook after successful **`TryCreateActive`**; **`reward_anomaly`** stub on economy validation deny.
- **`ContractCompletionOperations.TryCompleteOnEncounterClear`:** **`contract_complete`** hook extended to NEO-121 block style (NEO-149 partial comment completed).
- **`RewardRouterOperations.TryDeliverBundle` / `CompensatingRevertAll`:** **`reward_anomaly`** stub for partial-apply rollback; NEO-130 **`reward_delivery`** comment updated for contract **`SourceKind`**.
- **`RewardRouterOperations.TryDeliverBundle` / `CompensatingRevertAll`:** **`reward_anomaly`** stub for partial-apply rollback (single block on private **`CompensatingRevertAll`** — covers all four **`TryDeliverBundle`** call sites; DRY vs per-call-site duplicates); NEO-130 **`reward_delivery`** comment updated for contract **`SourceKind`**.
- **Docs:** `server/README.md` **Contract telemetry hooks (NEO-152)** subsection; E7.M4 module + alignment register + E7M4 backlog updated.
- **Tests:** no new tests — comments-only; **`dotnet test`** regression green.
## Technical approach
### 1. Current state (precursor partial work)
### 1. Shipped state (post-NEO-152)
| Location | State today | NEO-152 action |
|----------|-------------|----------------|
| **`ContractGeneratorOperations.TryIssue`** | Class doc references NEO-152; **no** hook at success or economy deny | **Add** `contract_issued` + `reward_anomaly` comment blocks |
| **`ContractCompletionOperations.TryCompleteOnEncounterClear`** | Partial **`contract_complete`** hook after **`TryMarkComplete`** (NEO-149) | **Verify/extend** to full NEO-121-style block (`TODO(E9.M1)` + payload fields) |
| **`RewardRouterOperations.TryDeliverBundle`** | NEO-130 **`reward_delivery`** at **`TryRecord`** success; **`CompensatingRevertAll`** with no anomaly stub | **Add** `reward_anomaly` stub comment at rollback invocations (shared quest + contract path) |
| **`server/README.md`** | Contract ops documented; **no** telemetry subsection | **Add** NEO-152 hook table; cross-link NEO-130 reward delivery for contract completions |
| Location | Shipped state |
|----------|---------------|
| **`ContractGeneratorOperations.TryIssue`** | **`contract_issued`** + economy-deny **`reward_anomaly`** comment blocks |
| **`ContractCompletionOperations.TryCompleteOnEncounterClear`** | Full NEO-121-style **`contract_complete`** hook after deliver-then-mark |
| **`RewardRouterOperations.CompensatingRevertAll`** | Single **`reward_anomaly`** stub (private method — all rollback call sites) |
| **`server/README.md`** | **Contract telemetry hooks (NEO-152)** subsection + NEO-130 cross-link |
### 2. Hook site A — `contract_issued`
@ -99,7 +99,7 @@ Anchor future E9.M1 catalog events **`contract_issued`**, **`contract_complete`*
**C2 — delivery rollback**
**Anchor:** **`RewardRouterOperations.TryDeliverBundle`**, at **`CompensatingRevertAll`** call sites after partial grant apply (skill XP / reputation / TryRecord race loser).
**Anchor:** private **`CompensatingRevertAll`** in **`RewardRouterOperations`** (invoked from four **`TryDeliverBundle`** rollback paths after partial grant apply — skill XP / reputation / TryRecord race loser). Single method-level stub covers all call sites (NEO-121 central **`Deny`** precedent).
- Stub comment names **`reward_anomaly`**; note E9.M1 filters by **`DeliveryTarget.SourceKind`** — contract completions use **`contract_completion`**.
- **Not** on: early denies before any grant apply (e.g. **`inventory_full`** simulation fail), idempotent **`TryGet`** replay, or successful **`TryRecord`**.
@ -112,7 +112,7 @@ Add **`### Contract telemetry hooks (NEO-152)`** after [Contract completion oper
|-------|--------|------|
| **`contract_issued`** | **`ContractGeneratorOperations.TryIssue`** | After successful **`TryCreateActive`** (active instance persisted). |
| **`contract_complete`** | **`ContractCompletionOperations.TryCompleteOnEncounterClear`** | After successful deliver-then-mark (instance marked complete + outcome appended). |
| **`reward_anomaly`** | **`ContractGeneratorOperations.TryIssue`** (economy deny); **`RewardRouterOperations.TryDeliverBundle`** (partial-apply rollback) | Economy cap / bundle cross-ref deny at issue; compensating revert after partial delivery apply. |
| **`reward_anomaly`** | **`ContractGeneratorOperations.TryIssue`** (economy deny); **`RewardRouterOperations.CompensatingRevertAll`** | Economy cap / bundle cross-ref deny at issue; compensating revert after partial delivery apply. |
| **`reward_delivery`** *(cross-link)* | **`RewardRouterOperations.TryDeliverBundle`** | NEO-130 — first-time **`TryRecord`** success; contract path uses **`SourceKind = contract_completion`**. |
### 6. Relationship to adjacent hooks
@ -166,7 +166,7 @@ None — comment-only changes to existing ops files and docs; no new source or t
|------|-----------|
| `server/NeonSprawl.Server/Game/Contracts/ContractGeneratorOperations.cs` | Add `contract_issued` hook after successful create; `reward_anomaly` stub on economy validation deny |
| `server/NeonSprawl.Server/Game/Contracts/ContractCompletionOperations.cs` | Verify/extend `contract_complete` hook block to NEO-121 style |
| `server/NeonSprawl.Server/Game/Rewards/RewardRouterOperations.cs` | Add `reward_anomaly` stub comments at `CompensatingRevertAll` invocations in `TryDeliverBundle` |
| `server/NeonSprawl.Server/Game/Rewards/RewardRouterOperations.cs` | Add `reward_anomaly` stub on private `CompensatingRevertAll` (covers all rollback call sites in `TryDeliverBundle`) |
| `server/README.md` | Add **Contract telemetry hooks (NEO-152)** subsection with event table + NEO-130 cross-link |
| `docs/decomposition/modules/E7_M4_ContractMissionGenerator.md` | Status line: E7M4-09 NEO-152 telemetry hooks landed |
| `docs/decomposition/modules/documentation_and_implementation_alignment.md` | E7.M4 row: E7M4-09 hook sites |

10
docs/reviews/2026-06-28-NEO-152.md
View File

@ -5,6 +5,8 @@
**Base:** `main`
**Issue:** [NEO-152](https://linear.app/neon-sprawl/issue/NEO-152) — E7M4-09 contract telemetry hook sites (comment-only)
**Follow-up:** Review suggestions addressed in docs-only follow-up commit.
## Verdict
**Approve with nits**
@ -22,7 +24,7 @@ Hook placement follows NEO-121/130/141 precedents (engine-only, **`TODO(E9.M1)`*
| `docs/plans/NEO-152-implementation-plan.md` | **Matches** — AC checklist complete; shipped reconciliation aligns with diff; kickoff decisions (engine-only, no duplicate `reward_delivery`, economy deny at orchestrator) reflected in code |
| `docs/plans/E7M4-pre-production-backlog.md` | **Matches** — E7M4-09 AC checked; landed note + README/plan links |
| `docs/decomposition/modules/E7_M4_ContractMissionGenerator.md` | **Matches** — NEO-152 telemetry hooks line added after NEO-151 HTTP |
| `docs/decomposition/modules/documentation_and_implementation_alignment.md` | **Partially matches** — E7.M4 row includes E7M4-09 / NEO-152 body text; trailing plan link list still jumps NEO-151 → label range without explicit **`NEO-152` plan** link (nit) |
| `docs/decomposition/modules/documentation_and_implementation_alignment.md` | **Matches** — E7.M4 row includes E7M4-09 / NEO-152 body text + explicit [NEO-152 plan](../../plans/NEO-152-implementation-plan.md) in trailing refs |
| `docs/decomposition/modules/module_dependency_register.md` | **Not re-read in diff** — no register change required; E7.M4 already tracked |
| `server/README.md` | **Matches** — **Contract telemetry hooks (NEO-152)** subsection with event table + NEO-130 cross-link |
| Client counterpart (NEO-153) | **N/A** — correctly out of scope; plan does not claim player-visible slice complete |
@ -35,14 +37,14 @@ None.
## Suggestions
1. **Add `NEO-152` plan link to alignment register footer** — The E7.M4 row body cites E7M4-09 / NEO-152, but the pipe-separated trailing refs list `[NEO-144]` … `[NEO-151]` then `label E7.M4 on NEO-144–NEO-154` without `[NEO-152 plan]`. Add for parity with adjacent landed stories.
1. ~~**Add `NEO-152` plan link to alignment register footer** — The E7.M4 row body cites E7M4-09 / NEO-152, but the pipe-separated trailing refs list `[NEO-144]` … `[NEO-151]` then `label E7.M4 on NEO-144–NEO-154` without `[NEO-152 plan]`. Add for parity with adjacent landed stories.~~ **Done.** Added `[NEO-152 plan]` to alignment register trailing refs.
2. **Note method-level vs call-site rollback anchor in plan** — Plan §4 C2 and the files table say stub comments at **`CompensatingRevertAll` invocations** in **`TryDeliverBundle`**; implementation uses a **single block on `CompensatingRevertAll`** (four call sites). Functionally equivalent and DRY (similar to NEO-121 central **`Deny`**); optional one-line note in plan **Implementation reconciliation** that the adopted anchor is the private method.
2. ~~**Note method-level vs call-site rollback anchor in plan** — Plan §4 C2 and the files table say stub comments at **`CompensatingRevertAll` invocations** in **`TryDeliverBundle`**; implementation uses a **single block on `CompensatingRevertAll`** (four call sites). Functionally equivalent and DRY (similar to NEO-121 central **`Deny`**); optional one-line note in plan **Implementation reconciliation** that the adopted anchor is the private method.~~ **Done.** Plan reconciliation, §1 (shipped state), §4 C2, README table, and files table updated.
## Nits
- Nit: **`reward_anomaly`** at economy validation deny is semantically a lint/cap deny rather than a delivery rollback; naming matches backlog/NEO-150 deferral — no change needed, but E9.M1 wiring should treat **`reasonCode`** distinctly from router rollback anomalies.
- Nit: Plan **§1 Current state** table still describes pre-ship “no hook” state; **Implementation reconciliation** is authoritative — optional cleanup of §1 on merge to past tense.
- ~~Nit: Plan **§1 Current state** table still describes pre-ship “no hook” state; **Implementation reconciliation** is authoritative — optional cleanup of §1 on merge to past tense.~~ **Done.** §1 renamed to **Shipped state (post-NEO-152)** with past-tense rows.
## Verification