# Client Canon Log Engine (Plan B) Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build the client-side GDScript engine that constructs the canon log at new-game (origin + world + character creation) and maintains its invariants turn to turn — a headless, GUT-tested logic layer that binds to the contract Plan A shipped.

**Architecture:** RefCounted typed entity classes each own the invariant guarding their own data (fat-but-decomposed model). A `NewGame` builder reads three immutable inputs (origin dict, `ContentDB`, character-creation dict) and writes two products (`CanonLog`, `GameState`); numeric Luck lives only in `GameState`, never the log. A pure `TagExtractor` parses §12 tags. No UI, no HTTP, no save/load. The api remains the authoritative schema gate; the client validates only the invariants it actively maintains.

**Tech Stack:** Godot 4.7, GDScript, GUT v9.7.1 (headless test runner). JSON everywhere; the client models the log as typed objects and serialises with `to_dict()`/`from_dict()`.

## Global Constraints

- **Engine:** Godot 4.7 (`/home/ptarrant/.local/bin/godot`, `4.7.stable`). GDScript only (charter §16).
- **Test framework:** GUT **v9.7.1**, vendored into `client/addons/gut`, run headless via `bash client/run_tests.sh`.
- **Model:** RefCounted typed classes with `to_dict()`/`from_dict()`. No `Resource`/`.tres`, no bare dictionaries for log entities (spec decision 3).
- **Validation:** invariants enforced **in the model** (correct-by-construction). No client-side JSON-Schema validator — the api is the schema authority (spec decision 4).
- **§7 Luck boundary:** numeric Luck, stats, HP/MP, inventory contents **never** appear in the canon log. Only `luck_descriptor` crosses. Enforced by keeping numbers in `GameState` and the log's `player` dict carrying exactly `{name, class_id, luck_descriptor}`.
- **`recent_events` capped at 5** (charter §11) — enforced by `CanonLog.push_event`.
- **POC classes:** `sellsword` | `assassin` | `priest` only (charter §8).
- **All string ids match `^[a-z0-9_]+$`** (via `Ids.is_valid`).
- **Test convention:** test files `extends "res://addons/gut/test.gd"` (path form, cache-independent) and `preload` the script-under-test by explicit `res://` path (a missing file is a clean red). Production code cross-references by `class_name`; `run_tests.sh` runs `godot --headless --import` first so those global names resolve.
- **Content root:** `ContentDB.default_content_root()` = `res://../content` globalized (dev reads the repo `/content`). Export packaging is a later plan.
- **Execution branch:** run this plan on `feature/client-canon-log-engine` branched off `dev` (CLAUDE.md §18). Per-task commits land there; the human merges to `dev`.

---

### Task 1: GUT harness — vendored, headless, smoke-tested

**Files:**
- Create: `client/addons/gut/` (vendored GUT v9.7.1)
- Create: `client/.gutconfig.json`
- Create: `client/run_tests.sh`
- Test: `client/tests/unit/test_smoke.gd`

**Interfaces:**
- Produces: `bash client/run_tests.sh` — imports the project then runs every `res://tests/unit/**/*.gd` GUT test; prints a summary containing `Failing: 0` when green. All later tasks invoke this exact command.

- [ ] **Step 1: Create the feature branch**

```bash
cd /home/ptarrant/repos/ptarrant/coc-rpg
git checkout dev && git checkout -b feature/client-canon-log-engine
```

- [ ] **Step 2: Vendor GUT v9.7.1 into the client**

```bash
cd /home/ptarrant/repos/ptarrant/coc-rpg
tmp=$(mktemp -d)
git clone --depth 1 --branch v9.7.1 https://github.com/bitwes/Gut.git "$tmp"
mkdir -p client/addons
cp -r "$tmp/addons/gut" client/addons/gut
rm -rf "$tmp"
ls client/addons/gut/gut_cmdln.gd
```
Expected: prints `client/addons/gut/gut_cmdln.gd` (the headless runner is present).

- [ ] **Step 3: Create the GUT config**

Create `client/.gutconfig.json`:

```json
{
  "dirs": ["res://tests/unit"],
  "include_subdirs": true,
  "log_level": 1,
  "should_exit": true
}
```

- [ ] **Step 4: Create the headless test runner**

Create `client/run_tests.sh`:

```bash
#!/usr/bin/env bash
# Headless GUT runner. Imports the project first so global class_name refs
# resolve on a fresh checkout / after new class_name scripts are added.
# Fallback if --import misbehaves on some builds: godot --headless --editor --quit
set -uo pipefail
cd "$(dirname "$0")"
godot --headless --import >/dev/null 2>&1 || true
godot --headless -s res://addons/gut/gut_cmdln.gd -gconfig=res://.gutconfig.json "$@"
```

Make it executable:

```bash
chmod +x /home/ptarrant/repos/ptarrant/coc-rpg/client/run_tests.sh
```

- [ ] **Step 5: Write the smoke test**

Create `client/tests/unit/test_smoke.gd`:

```gdscript
extends "res://addons/gut/test.gd"


func test_harness_runs():
	assert_eq(1, 1, "GUT harness executes a passing assertion")
```

- [ ] **Step 6: Run the harness**

Run: `bash client/run_tests.sh`
Expected: output contains `Passing: 1` and `Failing: 0`. This proves GUT runs headless against `tests/unit`.

- [ ] **Step 7: Commit**

```bash
cd /home/ptarrant/repos/ptarrant/coc-rpg
git add client/addons/gut client/.gutconfig.json client/run_tests.sh client/tests/unit/test_smoke.gd
git commit -m "chore(client): vendor GUT 9.7.1 + headless test harness"
```

---

### Task 2: Id helper + leaf canon-log entities

**Files:**
- Create: `client/scripts/ids.gd`
- Create: `client/scripts/canon_log/log_player.gd`
- Create: `client/scripts/canon_log/log_location.gd`
- Create: `client/scripts/canon_log/party_member.gd`
- Create: `client/scripts/canon_log/quest.gd`
- Create: `client/scripts/canon_log/humiliation.gd`
- Test: `client/tests/unit/test_entities.gd`

**Interfaces:**
- Produces:
  - `Ids.is_valid(id: String) -> bool`
  - `LogPlayer.new(name := "", class_id := "", luck_descriptor := "")`; `set_class_id(v) -> bool` (rejects non-POC classes); `to_dict() -> Dictionary` (exactly `{name, class_id, luck_descriptor}`); `LogPlayer.from_dict(d) -> LogPlayer`
  - `LogLocation.new(id := "", name := "")`; `to_dict()`; `LogLocation.from_dict(d) -> LogLocation`
  - `PartyMember.new(id := "", name := "", disposition := 0)`; `set_disposition(v)` (clamps −100..100); `to_dict()`; `PartyMember.from_dict(d) -> PartyMember`
  - `Quest.new(id := "", name := "", status := "active", objective := "")`; `set_status(v) -> bool` (enum); `to_dict()`; `Quest.from_dict(d) -> Quest`
  - `Humiliation.new(id := "", text := "", weight := 1, turn := 0)` (weight clamped 1..10, turn ≥ 0); `to_dict()`; `Humiliation.from_dict(d) -> Humiliation`

- [ ] **Step 1: Write the failing test**

Create `client/tests/unit/test_entities.gd`:

```gdscript
extends "res://addons/gut/test.gd"

const Ids = preload("res://scripts/ids.gd")
const LogPlayer = preload("res://scripts/canon_log/log_player.gd")
const LogLocation = preload("res://scripts/canon_log/log_location.gd")
const PartyMember = preload("res://scripts/canon_log/party_member.gd")
const Quest = preload("res://scripts/canon_log/quest.gd")
const Humiliation = preload("res://scripts/canon_log/humiliation.gd")


func test_ids_regex():
	assert_true(Ids.is_valid("greywater_docks"))
	assert_false(Ids.is_valid("Bad Id"))
	assert_false(Ids.is_valid("has-hyphen"))


func test_player_dict_has_only_three_keys():
	var p = LogPlayer.new("Aldric", "sellsword", "Fortune spits on you")
	var d = p.to_dict()
	assert_eq(d.keys().size(), 3)
	assert_false("luck" in d)
	assert_eq(d["class_id"], "sellsword")


func test_player_rejects_unknown_class():
	var p = LogPlayer.new("Aldric", "sellsword", "x")
	assert_false(p.set_class_id("bard"))
	assert_eq(p.class_id, "sellsword")


func test_party_member_clamps_disposition():
	var m = PartyMember.new("brannoc_thane", "Brannoc Thane", 200)
	assert_eq(m.disposition, 100)
	m.set_disposition(-200)
	assert_eq(m.disposition, -100)


func test_quest_status_enum():
	var q = Quest.new("find_the_ledger", "The Missing Ledger", "active", "Find it")
	assert_false(q.set_status("abandoned"))
	assert_eq(q.status, "active")
	assert_true(q.set_status("complete"))


func test_humiliation_clamps_weight_and_turn():
	var h = Humiliation.new("h_1", "vomited on a shrine", 11, -3)
	assert_eq(h.weight, 10)
	assert_eq(h.turn, 0)


func test_round_trip_each_entity():
	var loc = LogLocation.new("greywater_docks", "the Greywater docks")
	assert_eq(LogLocation.from_dict(loc.to_dict()).to_dict(), loc.to_dict())
	var m = PartyMember.new("cadwyn_vell", "Cadwyn Vell", 15)
	assert_eq(PartyMember.from_dict(m.to_dict()).to_dict(), m.to_dict())
```

- [ ] **Step 2: Run test to verify it fails**

Run: `bash client/run_tests.sh`
Expected: FAIL — the test script fails to load (`Could not load ... res://scripts/ids.gd`) or reports errors; `Failing`/errored count is non-zero.

- [ ] **Step 3: Write the Id helper**

Create `client/scripts/ids.gd`:

```gdscript
class_name Ids
extends RefCounted
## Shared id validation. Every canon-log / content id matches ^[a-z0-9_]+$.

static var _re: RegEx = RegEx.create_from_string("^[a-z0-9_]+$")


static func is_valid(id: String) -> bool:
	return _re.search(id) != null
```

- [ ] **Step 4: Write `LogPlayer`**

Create `client/scripts/canon_log/log_player.gd`:

```gdscript
class_name LogPlayer
extends RefCounted
## A canon-log player row. Carries ONLY name, class_id, luck_descriptor (§7):
## no numeric Luck, no stats — those live in GameState and never reach the AI.

const CLASSES := ["sellsword", "assassin", "priest"]

var name: String
var class_id: String
var luck_descriptor: String


func _init(p_name := "", p_class_id := "", p_luck_descriptor := "") -> void:
	name = p_name
	luck_descriptor = p_luck_descriptor
	if p_class_id != "":
		set_class_id(p_class_id)


func set_class_id(v: String) -> bool:
	if v not in CLASSES:
		push_error("invalid class_id: %s" % v)
		return false
	class_id = v
	return true


func to_dict() -> Dictionary:
	return {"name": name, "class_id": class_id, "luck_descriptor": luck_descriptor}


static func from_dict(d: Dictionary) -> LogPlayer:
	return LogPlayer.new(d.get("name", ""), d.get("class_id", ""), d.get("luck_descriptor", ""))
```

- [ ] **Step 5: Write `LogLocation`**

Create `client/scripts/canon_log/log_location.gd`:

```gdscript
class_name LogLocation
extends RefCounted
## A canon-log location row: id (code key) + name (prose).

var id: String
var name: String


func _init(p_id := "", p_name := "") -> void:
	if p_id != "" and not Ids.is_valid(p_id):
		push_error("invalid location id: %s" % p_id)
	id = p_id
	name = p_name


func to_dict() -> Dictionary:
	return {"id": id, "name": name}


static func from_dict(d: Dictionary) -> LogLocation:
	return LogLocation.new(d.get("id", ""), d.get("name", ""))
```

- [ ] **Step 6: Write `PartyMember`**

Create `client/scripts/canon_log/party_member.gd`:

```gdscript
class_name PartyMember
extends RefCounted
## A companion row. Owns the disposition clamp (−100..100, charter §9).

var id: String
var name: String
var disposition: int


func _init(p_id := "", p_name := "", p_disposition := 0) -> void:
	id = p_id
	name = p_name
	set_disposition(p_disposition)


func set_disposition(v: int) -> void:
	disposition = clampi(v, -100, 100)


func to_dict() -> Dictionary:
	return {"id": id, "name": name, "disposition": disposition}


static func from_dict(d: Dictionary) -> PartyMember:
	return PartyMember.new(d.get("id", ""), d.get("name", ""), int(d.get("disposition", 0)))
```

- [ ] **Step 7: Write `Quest`**

Create `client/scripts/canon_log/quest.gd`:

```gdscript
class_name Quest
extends RefCounted
## An active-quest row. Owns the status enum {active, complete, failed}.

const STATUSES := ["active", "complete", "failed"]

var id: String
var name: String
var status: String
var objective: String


func _init(p_id := "", p_name := "", p_status := "active", p_objective := "") -> void:
	id = p_id
	name = p_name
	objective = p_objective
	set_status(p_status)


func set_status(v: String) -> bool:
	if v not in STATUSES:
		push_error("invalid quest status: %s" % v)
		return false
	status = v
	return true


func to_dict() -> Dictionary:
	return {"id": id, "name": name, "status": status, "objective": objective}


static func from_dict(d: Dictionary) -> Quest:
	return Quest.new(d.get("id", ""), d.get("name", ""), d.get("status", "active"), d.get("objective", ""))
```

- [ ] **Step 8: Write `Humiliation`**

Create `client/scripts/canon_log/humiliation.gd`:

```gdscript
class_name Humiliation
extends RefCounted
## A Banter-memory row (charter §9). weight 1..10 drives reference frequency;
## turn drives decay. Append-only at the container level — these stack.

var id: String
var text: String
var weight: int
var turn: int


func _init(p_id := "", p_text := "", p_weight := 1, p_turn := 0) -> void:
	id = p_id
	text = p_text
	weight = clampi(p_weight, 1, 10)
	turn = maxi(p_turn, 0)


func to_dict() -> Dictionary:
	return {"id": id, "text": text, "weight": weight, "turn": turn}


static func from_dict(d: Dictionary) -> Humiliation:
	return Humiliation.new(d.get("id", ""), d.get("text", ""), int(d.get("weight", 1)), int(d.get("turn", 0)))
```

- [ ] **Step 9: Run test to verify it passes**

Run: `bash client/run_tests.sh`
Expected: PASS — output contains `Failing: 0`; the 7 `test_entities` tests all pass.

- [ ] **Step 10: Commit**

```bash
cd /home/ptarrant/repos/ptarrant/coc-rpg
git add client/scripts/ids.gd client/scripts/canon_log client/tests/unit/test_entities.gd
git commit -m "feat(client): id helper + leaf canon-log entities with owned invariants"
```

---

### Task 3: `CanonLog` container + maintenance mutators

**Files:**
- Create: `client/scripts/canon_log/canon_log.gd`
- Test: `client/tests/unit/test_canon_log.gd`

**Interfaces:**
- Consumes: `LogPlayer`, `LogLocation`, `PartyMember`, `Quest`, `Humiliation` (Task 2).
- Produces:
  - `CanonLog.new()` — starts with empty `LogPlayer`/`LogLocation`, empty arrays, `schema_version = 1`.
  - Mutators: `push_event(line)` (cap 5, drop oldest); `add_fact(text)` (dedup); `add_humiliation(id, text, weight, turn)` (append-only); `set_location(id, name)`; `party_member(id) -> PartyMember`; `adjust_disposition(id, delta) -> bool`; `set_quest_status(id, status) -> bool`.
  - `to_dict() -> Dictionary`; `CanonLog.from_dict(d) -> CanonLog` (returns `null` on unsupported `schema_version`).
  - Typed fields: `party: Array[PartyMember]`, `active_quests: Array[Quest]`, `humiliations: Array[Humiliation]`, `recent_events: Array[String]`, `established_facts: Array[String]`.

- [ ] **Step 1: Write the failing test**

Create `client/tests/unit/test_canon_log.gd`:

```gdscript
extends "res://addons/gut/test.gd"

const CanonLog = preload("res://scripts/canon_log/canon_log.gd")
const PartyMember = preload("res://scripts/canon_log/party_member.gd")
const Quest = preload("res://scripts/canon_log/quest.gd")


func test_push_event_caps_at_five():
	var log = CanonLog.new()
	for i in 7:
		log.push_event("event %d" % i)
	assert_eq(log.recent_events.size(), 5)
	assert_eq(log.recent_events[0], "event 2")
	assert_eq(log.recent_events[4], "event 6")


func test_add_fact_dedups():
	var log = CanonLog.new()
	log.add_fact("the bridge is out")
	log.add_fact("the bridge is out")
	assert_eq(log.established_facts.size(), 1)


func test_humiliations_stack():
	var log = CanonLog.new()
	log.add_humiliation("h_1", "vomited on a shrine", 7, 3)
	log.add_humiliation("h_2", "vomited on a shrine", 7, 5)
	assert_eq(log.humiliations.size(), 2)


func test_adjust_disposition_clamps_and_reports_missing():
	var log = CanonLog.new()
	log.party.append(PartyMember.new("brannoc_thane", "Brannoc Thane", 98))
	assert_true(log.adjust_disposition("brannoc_thane", 50))
	assert_eq(log.party_member("brannoc_thane").disposition, 100)
	assert_false(log.adjust_disposition("nobody", 5))


func test_set_quest_status_rejects_bad_enum():
	var log = CanonLog.new()
	log.active_quests.append(Quest.new("find_the_ledger", "The Missing Ledger", "active", "Find it"))
	assert_false(log.set_quest_status("find_the_ledger", "abandoned"))
	assert_true(log.set_quest_status("find_the_ledger", "complete"))
	assert_false(log.set_quest_status("no_quest", "active"))


func test_unsupported_schema_version_returns_null():
	assert_null(CanonLog.from_dict({"schema_version": 2}))
```

- [ ] **Step 2: Run test to verify it fails**

Run: `bash client/run_tests.sh`
Expected: FAIL — `Could not load ... res://scripts/canon_log/canon_log.gd`; non-zero failing/errored.

- [ ] **Step 3: Write `CanonLog`**

Create `client/scripts/canon_log/canon_log.gd`:

```gdscript
class_name CanonLog
extends RefCounted
## The §11 canon log: compact structured state code maintains and injects into
## every AI call. This container owns the container-level invariants; leaf rows
## own theirs. AI prose never writes here directly — mutators are called by code.

const SCHEMA_VERSION := 1
const MAX_RECENT_EVENTS := 5

var schema_version: int = SCHEMA_VERSION
var player: LogPlayer
var location: LogLocation
var party: Array[PartyMember] = []
var recent_events: Array[String] = []
var established_facts: Array[String] = []
var active_quests: Array[Quest] = []
var humiliations: Array[Humiliation] = []


func _init() -> void:
	player = LogPlayer.new()
	location = LogLocation.new()


# ── maintenance mutators (charter §11 maintenance table) ─────────────────────

func push_event(line: String) -> void:
	recent_events.append(line)
	while recent_events.size() > MAX_RECENT_EVENTS:
		recent_events.pop_front()


func add_fact(text: String) -> void:
	if text not in established_facts:
		established_facts.append(text)


func add_humiliation(id: String, text: String, weight: int, turn: int) -> void:
	humiliations.append(Humiliation.new(id, text, weight, turn))


func set_location(id: String, name: String) -> void:
	location = LogLocation.new(id, name)


func party_member(id: String) -> PartyMember:
	for m in party:
		if m.id == id:
			return m
	return null


func adjust_disposition(id: String, delta: int) -> bool:
	var m := party_member(id)
	if m == null:
		return false
	m.set_disposition(m.disposition + delta)
	return true


func set_quest_status(id: String, status: String) -> bool:
	for q in active_quests:
		if q.id == id:
			return q.set_status(status)
	return false


# ── serialisation ────────────────────────────────────────────────────────────

func to_dict() -> Dictionary:
	return {
		"schema_version": schema_version,
		"player": player.to_dict(),
		"location": location.to_dict(),
		"party": party.map(func(m): return m.to_dict()),
		"recent_events": recent_events.duplicate(),
		"established_facts": established_facts.duplicate(),
		"active_quests": active_quests.map(func(q): return q.to_dict()),
		"humiliations": humiliations.map(func(h): return h.to_dict()),
	}


static func from_dict(d: Dictionary) -> CanonLog:
	var v := int(d.get("schema_version", -1))
	if v != SCHEMA_VERSION:
		push_error("unsupported canon_log schema_version: %s" % v)
		return null
	var log := CanonLog.new()
	log.player = LogPlayer.from_dict(d.get("player", {}))
	log.location = LogLocation.from_dict(d.get("location", {}))
	for m in d.get("party", []):
		log.party.append(PartyMember.from_dict(m))
	for e in d.get("recent_events", []):
		log.push_event(e)
	for f in d.get("established_facts", []):
		log.add_fact(f)
	for q in d.get("active_quests", []):
		log.active_quests.append(Quest.from_dict(q))
	for h in d.get("humiliations", []):
		log.humiliations.append(Humiliation.from_dict(h))
	return log
```

- [ ] **Step 4: Run test to verify it passes**

Run: `bash client/run_tests.sh`
Expected: PASS — `Failing: 0`; the 6 `test_canon_log` tests pass. (The `push_error` on the unsupported-version test prints a red line but does not fail the test — GUT does not fail on `push_error` by default.)

- [ ] **Step 5: Commit**

```bash
cd /home/ptarrant/repos/ptarrant/coc-rpg
git add client/scripts/canon_log/canon_log.gd client/tests/unit/test_canon_log.gd
git commit -m "feat(client): CanonLog container + maintenance mutators (cap 5, dedup, stack)"
```

---

### Task 4: `Luck` + `GameState` (the §7 numeric store)

**Files:**
- Create: `client/scripts/state/luck.gd`
- Create: `client/scripts/state/game_state.gd`
- Test: `client/tests/unit/test_luck.gd`, `client/tests/unit/test_game_state.gd`

**Interfaces:**
- Produces:
  - `Luck.MIN`(1), `Luck.MAX`(20), `Luck.DRIFT`(3); `Luck.roll_base(rng: RandomNumberGenerator, modifier: int) -> int`; `Luck.drift(current: int, base: int, delta: int) -> int`; `Luck.descriptor(luck: int) -> String`.
  - `GameState.new()` with fields `luck: int`, `luck_base: int`, `stats: Dictionary`, `npc_dispositions: Dictionary`, `inventory: Dictionary`; methods `set_luck(v)`, `drift_luck(delta)`, `luck_descriptor() -> String`, `set_npc_disposition(id, v)` (clamp −100..100), `add_item(item_id, qty)`.

- [ ] **Step 1: Write the failing Luck test**

Create `client/tests/unit/test_luck.gd`:

```gdscript
extends "res://addons/gut/test.gd"

const Luck = preload("res://scripts/state/luck.gd")


func _rng(s: int) -> RandomNumberGenerator:
	var r := RandomNumberGenerator.new()
	r.seed = s
	return r


func test_roll_base_is_deterministic_for_a_seed():
	assert_eq(Luck.roll_base(_rng(42), 0), Luck.roll_base(_rng(42), 0))


func test_roll_base_stays_in_range():
	for s in range(1, 30):
		var v := Luck.roll_base(_rng(s), 0)
		assert_true(v >= Luck.MIN and v <= Luck.MAX, "luck %d out of range" % v)


func test_modifier_shifts_result():
	# +100 modifier clamps to MAX regardless of rolls.
	assert_eq(Luck.roll_base(_rng(5), 100), Luck.MAX)


func test_drift_stays_within_base_band_and_range():
	assert_eq(Luck.drift(10, 10, 100), 13)   # capped at base+3
	assert_eq(Luck.drift(10, 10, -100), 7)    # capped at base-3
	assert_eq(Luck.drift(20, 19, 100), 20)    # base+3=22 -> clamped to MAX


func test_descriptor_bands():
	assert_eq(Luck.descriptor(4), "Fortune spits on you")
	assert_eq(Luck.descriptor(5), "The world is not on your side")
	assert_eq(Luck.descriptor(20), "The dice are kind today")
```

- [ ] **Step 2: Run test to verify it fails**

Run: `bash client/run_tests.sh`
Expected: FAIL — `Could not load ... res://scripts/state/luck.gd`.

- [ ] **Step 3: Write `Luck`**

Create `client/scripts/state/luck.gd`:

```gdscript
class_name Luck
extends RefCounted
## Numeric Luck (charter §7). Lives in GameState; only descriptor() reaches the
## log. Deterministic given a seeded RNG (charter §10). Die/range/bands are
## TUNABLE constants — not final values.

const MIN := 1
const MAX := 20
const DRIFT := 3

const BANDS := [
	{"max": 4, "text": "Fortune spits on you"},
	{"max": 8, "text": "The world is not on your side"},
	{"max": 12, "text": "The dice are indifferent"},
	{"max": 16, "text": "Luck rides with you"},
	{"max": 20, "text": "The dice are kind today"},
]


static func roll_base(rng: RandomNumberGenerator, modifier: int) -> int:
	var total := 0
	for i in 5:
		total += rng.randi_range(1, 20)
	return clampi(roundi(total / 5.0) + modifier, MIN, MAX)


static func drift(current: int, base: int, delta: int) -> int:
	return clampi(clampi(current + delta, base - DRIFT, base + DRIFT), MIN, MAX)


static func descriptor(luck: int) -> String:
	for band in BANDS:
		if luck <= band["max"]:
			return band["text"]
	return BANDS[-1]["text"]
```

- [ ] **Step 4: Run test to verify it passes**

Run: `bash client/run_tests.sh`
Expected: PASS — the 5 `test_luck` tests pass, `Failing: 0`.

- [ ] **Step 5: Write the failing GameState test**

Create `client/tests/unit/test_game_state.gd`:

```gdscript
extends "res://addons/gut/test.gd"

const GameState = preload("res://scripts/state/game_state.gd")


func test_add_item_accumulates():
	var s = GameState.new()
	s.add_item("coin", 3)
	s.add_item("coin", 2)
	assert_eq(s.inventory["coin"], 5)


func test_npc_disposition_clamps():
	var s = GameState.new()
	s.set_npc_disposition("oda_fenn", 250)
	assert_eq(s.npc_dispositions["oda_fenn"], 100)


func test_drift_luck_respects_base():
	var s = GameState.new()
	s.luck_base = 10
	s.luck = 10
	s.drift_luck(100)
	assert_eq(s.luck, 13)


func test_luck_descriptor_delegates():
	var s = GameState.new()
	s.luck = 4
	assert_eq(s.luck_descriptor(), "Fortune spits on you")
```

- [ ] **Step 6: Run test to verify it fails**

Run: `bash client/run_tests.sh`
Expected: FAIL — `Could not load ... res://scripts/state/game_state.gd`.

- [ ] **Step 7: Write `GameState`**

Create `client/scripts/state/game_state.gd`:

```gdscript
class_name GameState
extends RefCounted
## Luck-centric game state (spec decision 5). The SOLE home of numeric Luck,
## stats, world-NPC dispositions, and inventory — none of which enter the canon
## log (charter §7/§2). The log reads only luck_descriptor() from here.

var luck: int = 0
var luck_base: int = 0
var stats: Dictionary = {}            # {str, dex, con, fth, mag}
var npc_dispositions: Dictionary = {} # world-npc id -> int (−100..100)
var inventory: Dictionary = {}        # item_id -> qty


func set_luck(v: int) -> void:
	luck = clampi(v, Luck.MIN, Luck.MAX)


func drift_luck(delta: int) -> void:
	luck = Luck.drift(luck, luck_base, delta)


func luck_descriptor() -> String:
	return Luck.descriptor(luck)


func set_npc_disposition(id: String, v: int) -> void:
	npc_dispositions[id] = clampi(v, -100, 100)


func add_item(item_id: String, qty: int) -> void:
	inventory[item_id] = int(inventory.get(item_id, 0)) + qty
```

- [ ] **Step 8: Run test to verify it passes**

Run: `bash client/run_tests.sh`
Expected: PASS — the 4 `test_game_state` tests pass, `Failing: 0`.

- [ ] **Step 9: Commit**

```bash
cd /home/ptarrant/repos/ptarrant/coc-rpg
git add client/scripts/state client/tests/unit/test_luck.gd client/tests/unit/test_game_state.gd
git commit -m "feat(client): Luck (deterministic gen/drift/descriptor) + GameState store"
```

---

### Task 5: `ContentDB` — load `/content`, resolve origin refs

**Files:**
- Create: `client/scripts/content/content_db.gd`
- Test: `client/tests/unit/test_content_db.gd`

**Interfaces:**
- Consumes: the authored fixtures under `/content` (Plan A).
- Produces:
  - `ContentDB.default_content_root() -> String` (globalized `res://../content`)
  - `ContentDB.origin_path(id: String) -> String`
  - `ContentDB.load_json(abs_path: String) -> Variant`
  - `ContentDB.new()`; `load_from(content_root: String) -> void`
  - Lookups returning the raw content dict (or `{}`): `location(id)`, `npc(id)`, `quest(id)`, `item(id)`; predicates `has_location/has_npc/has_quest/has_item(id) -> bool`
  - `companions() -> Array` (NPC dicts with `role == "companion"`)
  - `unresolved_refs(origin: Dictionary) -> Array` (e.g. `["location:nowhere", "item:ghost_blade"]`; empty = clean) — the GDScript twin of `api/app/content.py::unresolved_refs`.

- [ ] **Step 1: Write the failing test**

Create `client/tests/unit/test_content_db.gd`:

```gdscript
extends "res://addons/gut/test.gd"

const ContentDB = preload("res://scripts/content/content_db.gd")

var db


func before_each():
	db = ContentDB.new()
	db.load_from(ContentDB.default_content_root())


func _deserter() -> Dictionary:
	return ContentDB.load_json(ContentDB.origin_path("deserter"))


func test_loads_world_ids():
	assert_true(db.has_location("greywater_docks"))
	assert_true(db.has_quest("find_the_ledger"))
	assert_true(db.has_item("worn_shortsword"))
	assert_true(db.has_item("coin"))


func test_companions_are_brannoc_and_cadwyn():
	var ids := []
	for n in db.companions():
		ids.append(n["id"])
	ids.sort()
	assert_eq(ids, ["brannoc_thane", "cadwyn_vell"])


func test_good_origin_has_no_unresolved_refs():
	assert_eq(db.unresolved_refs(_deserter()), [])


func test_broken_location_ref_detected():
	var o := _deserter()
	o["start_location_id"] = "nowhere"
	assert_true("location:nowhere" in db.unresolved_refs(o))


func test_broken_item_ref_detected():
	var o := _deserter()
	o["inventory_grants"] = o["inventory_grants"].duplicate(true)
	o["inventory_grants"].append({"item_id": "ghost_blade", "qty": 1})
	assert_true("item:ghost_blade" in db.unresolved_refs(o))


func test_null_quest_ref_resolves():
	var o := _deserter()
	o["start_quest_id"] = null
	assert_eq(db.unresolved_refs(o), [])
```

- [ ] **Step 2: Run test to verify it fails**

Run: `bash client/run_tests.sh`
Expected: FAIL — `Could not load ... res://scripts/content/content_db.gd`.

- [ ] **Step 3: Write `ContentDB`**

Create `client/scripts/content/content_db.gd`:

```gdscript
class_name ContentDB
extends RefCounted
## Loads authored world content (/content) and cross-checks origin references.
## Mirrors api/app/content.py so client and api resolve ids identically. This is
## content integrity, distinct from JSON-schema validation.

var locations: Dictionary = {}
var npcs: Dictionary = {}
var quests: Dictionary = {}
var items: Dictionary = {}


static func default_content_root() -> String:
	return ProjectSettings.globalize_path("res://").path_join("../content").simplify_path()


static func origin_path(id: String) -> String:
	return default_content_root().path_join("origins").path_join("%s.json" % id)


static func load_json(abs_path: String) -> Variant:
	var text := FileAccess.get_file_as_string(abs_path)
	return JSON.parse_string(text)


func load_from(content_root: String) -> void:
	var world := content_root.path_join("world")
	locations = _load_dir(world.path_join("locations"))
	npcs = _load_dir(world.path_join("npcs"))
	quests = _load_dir(world.path_join("quests"))
	items = _load_dir(world.path_join("items"))


func _load_dir(dir_path: String) -> Dictionary:
	var out: Dictionary = {}
	var dir := DirAccess.open(dir_path)
	if dir == null:
		push_error("content dir not found: %s" % dir_path)
		return out
	for file in dir.get_files():
		if not file.ends_with(".json"):
			continue
		var data: Variant = load_json(dir_path.path_join(file))
		if typeof(data) != TYPE_DICTIONARY or not data.has("id"):
			push_error("bad content file: %s" % file)
			continue
		out[data["id"]] = data
	return out


func location(id: String) -> Dictionary: return locations.get(id, {})
func npc(id: String) -> Dictionary: return npcs.get(id, {})
func quest(id: String) -> Dictionary: return quests.get(id, {})
func item(id: String) -> Dictionary: return items.get(id, {})
func has_location(id: String) -> bool: return locations.has(id)
func has_npc(id: String) -> bool: return npcs.has(id)
func has_quest(id: String) -> bool: return quests.has(id)
func has_item(id: String) -> bool: return items.has(id)


func companions() -> Array:
	var out: Array = []
	for id in npcs:
		if npcs[id].get("role", "") == "companion":
			out.append(npcs[id])
	return out


func unresolved_refs(origin: Dictionary) -> Array:
	var missing: Array = []
	var loc: String = origin.get("start_location_id", "")
	if not has_location(loc):
		missing.append("location:%s" % loc)
	var q: Variant = origin.get("start_quest_id", null)
	if q != null and not has_quest(q):
		missing.append("quest:%s" % q)
	for grant in origin.get("inventory_grants", []):
		if not has_item(grant.get("item_id", "")):
			missing.append("item:%s" % grant.get("item_id", ""))
	for npc_id in origin.get("disposition_overrides", {}):
		if not has_npc(npc_id):
			missing.append("npc:%s" % npc_id)
	return missing
```

- [ ] **Step 4: Run test to verify it passes**

Run: `bash client/run_tests.sh`
Expected: PASS — the 6 `test_content_db` tests pass, `Failing: 0`. (Proves the globalized `res://../content` path reaches the real repo fixtures headless.)

- [ ] **Step 5: Commit**

```bash
cd /home/ptarrant/repos/ptarrant/coc-rpg
git add client/scripts/content/content_db.gd client/tests/unit/test_content_db.gd
git commit -m "feat(client): ContentDB loads /content + mirrors the api id-resolution check"
```

---

### Task 6: `NewGame.construct` — origin + world + creation → {log, state}

**Files:**
- Create: `client/scripts/newgame/new_game.gd`
- Test: `client/tests/unit/test_new_game.gd`

**Interfaces:**
- Consumes: `CanonLog`, `LogPlayer`, `PartyMember`, `Quest` (Tasks 2–3); `Luck`, `GameState` (Task 4); `ContentDB` (Task 5).
- Produces: `NewGame.construct(origin: Dictionary, world: ContentDB, creation: Dictionary, rng: RandomNumberGenerator) -> Dictionary`, returning `{ ok: bool, errors: Array, log: CanonLog, state: GameState }`. `creation` = `{name, class_id}`. On any content-integrity or build-constraint failure, `ok` is `false`, `errors` is non-empty, and `log`/`state` are `null`.

- [ ] **Step 1: Write the failing test**

Create `client/tests/unit/test_new_game.gd`:

```gdscript
extends "res://addons/gut/test.gd"

const NewGame = preload("res://scripts/newgame/new_game.gd")
const ContentDB = preload("res://scripts/content/content_db.gd")

var world


func before_each():
	world = ContentDB.new()
	world.load_from(ContentDB.default_content_root())


func _deserter() -> Dictionary:
	return ContentDB.load_json(ContentDB.origin_path("deserter"))


func _rng() -> RandomNumberGenerator:
	var r := RandomNumberGenerator.new()
	r.seed = 7
	return r


func _build(creation: Dictionary) -> Dictionary:
	return NewGame.construct(_deserter(), world, creation, _rng())


func test_construct_succeeds():
	var res := _build({"name": "Aldric", "class_id": "sellsword"})
	assert_true(res["ok"], str(res["errors"]))


func test_numeric_luck_absent_from_log():
	var res := _build({"name": "Aldric", "class_id": "sellsword"})
	var pd: Dictionary = res["log"].player.to_dict()
	assert_false("luck" in pd)
	assert_eq(pd.keys().size(), 3)
	assert_true(res["state"].luck >= Luck.MIN and res["state"].luck <= Luck.MAX)


func test_inventory_and_dispo_land_in_state_not_log():
	var res := _build({"name": "Aldric", "class_id": "sellsword"})
	assert_eq(res["state"].inventory.get("coin", 0), 3)
	assert_eq(res["state"].inventory.get("worn_shortsword", 0), 1)
	assert_false("inventory" in res["log"].to_dict())


func test_companion_dispositions_from_overrides():
	var res := _build({"name": "Aldric", "class_id": "sellsword"})
	assert_eq(res["log"].party_member("brannoc_thane").disposition, 40)
	assert_eq(res["log"].party_member("cadwyn_vell").disposition, 15)


func test_situation_and_facts_seeded():
	var res := _build({"name": "Aldric", "class_id": "sellsword"})
	assert_eq(res["log"].recent_events.size(), 2)
	assert_true("the player deserted the Iron Kettle mercenary company" in res["log"].established_facts)
	assert_eq(res["log"].humiliations.size(), 0)


func test_active_quest_resolved_from_world():
	var res := _build({"name": "Aldric", "class_id": "sellsword"})
	assert_eq(res["log"].active_quests.size(), 1)
	assert_eq(res["log"].active_quests[0].id, "find_the_ledger")
	assert_eq(res["log"].active_quests[0].status, "active")


func test_null_start_quest_yields_no_quest():
	var o := _deserter()
	o["start_quest_id"] = null
	var res := NewGame.construct(o, world, {"name": "X", "class_id": "sellsword"}, _rng())
	assert_eq(res["log"].active_quests.size(), 0)


func test_class_not_allowed_is_rejected():
	var res := _build({"name": "X", "class_id": "berserker"})
	assert_false(res["ok"])
	assert_true(res["errors"].size() > 0)
	assert_null(res["log"])


func test_unresolved_origin_is_rejected():
	var o := _deserter()
	o["start_location_id"] = "nowhere"
	var res := NewGame.construct(o, world, {"name": "X", "class_id": "sellsword"}, _rng())
	assert_false(res["ok"])
	assert_true("unresolved ref: location:nowhere" in res["errors"])
```

- [ ] **Step 2: Run test to verify it fails**

Run: `bash client/run_tests.sh`
Expected: FAIL — `Could not load ... res://scripts/newgame/new_game.gd`.

- [ ] **Step 3: Write `NewGame`**

Create `client/scripts/newgame/new_game.gd`:

```gdscript
class_name NewGame
extends RefCounted
## New-game construction (spec "New-game construction"). Reads three immutable
## inputs (origin, world, creation) and writes two products (CanonLog, GameState).
## Nothing flows back up — charter §2 on the client. Validation is front-loaded:
## a broken origin or illegal class fails here, loudly, not three scenes later.

static func construct(origin: Dictionary, world: ContentDB, creation: Dictionary, rng: RandomNumberGenerator) -> Dictionary:
	var errors: Array = []

	# 1. content integrity — every referenced id must resolve in world content.
	for ref in world.unresolved_refs(origin):
		errors.append("unresolved ref: %s" % ref)

	# 2. build constraints — chosen class must be allowed by the origin.
	var bc: Dictionary = origin.get("build_constraints", {})
	var allowed: Array = bc.get("allowed_classes", [])
	var class_id: String = creation.get("class_id", "")
	if class_id not in allowed:
		errors.append("class not allowed by origin: %s" % class_id)

	if not errors.is_empty():
		return {"ok": false, "errors": errors, "log": null, "state": null}

	# 3. roll Luck (numeric -> state only) and 4. the stat block (data only).
	var state := GameState.new()
	state.luck_base = Luck.roll_base(rng, int(bc.get("luck_modifier", 0)))
	state.luck = state.luck_base
	state.stats = {
		"str": _roll_stat(rng), "dex": _roll_stat(rng), "con": _roll_stat(rng),
		"fth": _roll_stat(rng), "mag": _roll_stat(rng),
	}

	# 5. assemble the canon log.
	var log := CanonLog.new()
	log.player = LogPlayer.new(creation.get("name", ""), class_id, state.luck_descriptor())

	var loc: Dictionary = world.location(origin["start_location_id"])
	log.set_location(loc.get("id", ""), loc.get("name", ""))

	var overrides: Dictionary = origin.get("disposition_overrides", {})
	var companion_ids := {}
	for c in world.companions():
		companion_ids[c["id"]] = true
		log.party.append(PartyMember.new(c["id"], c.get("name", ""), int(overrides.get(c["id"], 0))))
	# non-companion overrides go to game state, never the log (spec §5 / charter §6).
	for npc_id in overrides:
		if not companion_ids.has(npc_id):
			state.set_npc_disposition(npc_id, int(overrides[npc_id]))

	for line in origin.get("situation", []):
		log.push_event(line)
	for fact in origin.get("opening_facts", []):
		log.add_fact(fact)

	var quest_id: Variant = origin.get("start_quest_id", null)
	if quest_id != null:
		var qd: Dictionary = world.quest(quest_id)
		log.active_quests.append(Quest.new(qd.get("id", ""), qd.get("name", ""), "active", qd.get("objective", "")))

	# inventory grants -> game state (NOT the log). Charter §2.
	for grant in origin.get("inventory_grants", []):
		state.add_item(grant.get("item_id", ""), int(grant.get("qty", 0)))

	return {"ok": true, "errors": [], "log": log, "state": state}


static func _roll_stat(rng: RandomNumberGenerator) -> int:
	# 3d6 placeholder; the stat block is data-only in this plan. TUNABLE.
	return rng.randi_range(1, 6) + rng.randi_range(1, 6) + rng.randi_range(1, 6)
```

- [ ] **Step 4: Run test to verify it passes**

Run: `bash client/run_tests.sh`
Expected: PASS — the 9 `test_new_game` tests pass, `Failing: 0`. (End-to-end construction from the real `deserter.json` produces a correct log + state.)

- [ ] **Step 5: Commit**

```bash
cd /home/ptarrant/repos/ptarrant/coc-rpg
git add client/scripts/newgame/new_game.gd client/tests/unit/test_new_game.gd
git commit -m "feat(client): NewGame.construct — origin+world+creation -> {canon log, state}"
```

---

### Task 7: `TagExtractor` — pure §12 tag parsing

**Files:**
- Create: `client/scripts/text/tag_extractor.gd`
- Test: `client/tests/unit/test_tag_extractor.gd`

**Interfaces:**
- Produces: `TagExtractor.extract(prose: String) -> Dictionary` returning `{ clean_text: String, facts: Array, dispositions: Array, moves: Array }`, where each `moves` entry is `{name: String, args: Array}`. Extracts and strips only — no state mutation, no move validation (deferred to the HTTP plan).

- [ ] **Step 1: Write the failing test**

Create `client/tests/unit/test_tag_extractor.gd`:

```gdscript
extends "res://addons/gut/test.gd"

const TagExtractor = preload("res://scripts/text/tag_extractor.gd")


func test_fact_extracted_and_stripped():
	var r := TagExtractor.extract("A muddy road. [FACT: the eastern bridge is out]")
	assert_eq(r["facts"], ["the eastern bridge is out"])
	assert_eq(r["clean_text"], "A muddy road.")


func test_positive_and_negative_disposition():
	assert_eq(TagExtractor.extract("\"Aye.\" [ADJUST_DISPOSITION: +5]")["dispositions"], [5])
	assert_eq(TagExtractor.extract("[ADJUST_DISPOSITION: -10]")["dispositions"], [-10])


func test_move_parsed_with_args():
	var r := TagExtractor.extract("[MOVE: offer_quest(14)]")
	assert_eq(r["moves"][0]["name"], "offer_quest")
	assert_eq(r["moves"][0]["args"], ["14"])


func test_move_with_no_args():
	var r := TagExtractor.extract("[MOVE: refuse()]")
	assert_eq(r["moves"][0]["name"], "refuse")
	assert_eq(r["moves"][0]["args"], [])


func test_multiple_facts_collected():
	var r := TagExtractor.extract("Hi [FACT: a] mid [FACT: b] end")
	assert_eq(r["facts"], ["a", "b"])
	assert_eq(r["clean_text"], "Hi mid end")


func test_no_tags_is_clean_passthrough():
	var r := TagExtractor.extract("no tags here")
	assert_eq(r["facts"], [])
	assert_eq(r["dispositions"], [])
	assert_eq(r["moves"], [])
	assert_eq(r["clean_text"], "no tags here")
```

- [ ] **Step 2: Run test to verify it fails**

Run: `bash client/run_tests.sh`
Expected: FAIL — `Could not load ... res://scripts/text/tag_extractor.gd`.

- [ ] **Step 3: Write `TagExtractor`**

Create `client/scripts/text/tag_extractor.gd`:

```gdscript
class_name TagExtractor
extends RefCounted
## Pure §12 tag parsing. Extracts [FACT:], [ADJUST_DISPOSITION:], [MOVE:] tags
## and returns the prose with all tags stripped. It never applies anything and
## never validates a move (that needs NPC context from /npc/speak — a later
## plan). Its outputs are exactly the inputs CanonLog's mutators consume.

static var _fact_re: RegEx = RegEx.create_from_string("\\[FACT:\\s*(.*?)\\]")
static var _dispo_re: RegEx = RegEx.create_from_string("\\[ADJUST_DISPOSITION:\\s*([+-]?\\d+)\\]")
static var _move_re: RegEx = RegEx.create_from_string("\\[MOVE:\\s*(\\w+)\\(([^)]*)\\)\\]")
static var _any_re: RegEx = RegEx.create_from_string("\\[[A-Z_]+:[^\\]]*\\]")


static func extract(prose: String) -> Dictionary:
	var facts: Array = []
	for m in _fact_re.search_all(prose):
		facts.append(m.get_string(1).strip_edges())

	var dispositions: Array = []
	for m in _dispo_re.search_all(prose):
		dispositions.append(int(m.get_string(1)))

	var moves: Array = []
	for m in _move_re.search_all(prose):
		var raw_args := m.get_string(2).strip_edges()
		var args: Array = []
		if raw_args != "":
			for a in raw_args.split(","):
				args.append(a.strip_edges())
		moves.append({"name": m.get_string(1), "args": args})

	var clean := _any_re.sub(prose, "", true)
	# Collapse whitespace left where inline tags were removed.
	while clean.contains("  "):
		clean = clean.replace("  ", " ")
	clean = clean.strip_edges()

	return {"clean_text": clean, "facts": facts, "dispositions": dispositions, "moves": moves}
```

- [ ] **Step 4: Run test to verify it passes**

Run: `bash client/run_tests.sh`
Expected: PASS — the 6 `test_tag_extractor` tests pass, `Failing: 0`.

- [ ] **Step 5: Commit**

```bash
cd /home/ptarrant/repos/ptarrant/coc-rpg
git add client/scripts/text/tag_extractor.gd client/tests/unit/test_tag_extractor.gd
git commit -m "feat(client): TagExtractor — pure regex parse/strip of §12 tags"
```

---

### Task 8: Round-trip + integration — the bridge to the api contract

**Files:**
- Test: `client/tests/unit/test_round_trip.gd`

**Interfaces:**
- Consumes: `NewGame` (Task 6), `ContentDB` (Task 5), `CanonLog` (Task 3).
- Produces: no new production code — this task proves the client's product survives `to_dict → from_dict` unchanged and satisfies every contract invariant the api enforces (spec decision 4: parity without duplicating the schema).

- [ ] **Step 1: Write the integration test**

Create `client/tests/unit/test_round_trip.gd`:

```gdscript
extends "res://addons/gut/test.gd"

const NewGame = preload("res://scripts/newgame/new_game.gd")
const ContentDB = preload("res://scripts/content/content_db.gd")
const CanonLog = preload("res://scripts/canon_log/canon_log.gd")


func _built_log():
	var world = ContentDB.new()
	world.load_from(ContentDB.default_content_root())
	var rng := RandomNumberGenerator.new()
	rng.seed = 3
	var origin := ContentDB.load_json(ContentDB.origin_path("deserter"))
	var res := NewGame.construct(origin, world, {"name": "Aldric", "class_id": "priest"}, rng)
	assert_true(res["ok"], str(res["errors"]))
	return res["log"]


func test_to_from_dict_is_identity():
	var log = _built_log()
	var d1: Dictionary = log.to_dict()
	var log2 = CanonLog.from_dict(d1)
	assert_not_null(log2)
	assert_eq(log2.to_dict(), d1)


func test_constructed_log_satisfies_contract_invariants():
	var d: Dictionary = _built_log().to_dict()
	assert_eq(d["schema_version"], 1)
	assert_true(d["recent_events"].size() <= 5)
	assert_eq(d["player"].keys().size(), 3)          # exactly name/class_id/luck_descriptor
	assert_false("luck" in d["player"])              # §7: no numeric luck
	assert_true(d["player"]["class_id"] in ["sellsword", "assassin", "priest"])
	for m in d["party"]:
		assert_true(m["disposition"] >= -100 and m["disposition"] <= 100)
	for q in d["active_quests"]:
		assert_true(q["status"] in ["active", "complete", "failed"])
	for h in d["humiliations"]:
		assert_true(h["weight"] >= 1 and h["weight"] <= 10)
```

- [ ] **Step 2: Run the full suite**

Run: `bash client/run_tests.sh`
Expected: PASS — every test from Tasks 1–8 green, `Failing: 0`. The `test_round_trip` pair proves the client's canon log conforms to the same contract the api validates, with no schema re-implementation.

- [ ] **Step 3: Commit**

```bash
cd /home/ptarrant/repos/ptarrant/coc-rpg
git add client/tests/unit/test_round_trip.gd
git commit -m "test(client): round-trip + contract-invariant integration on a constructed log"
```

- [ ] **Step 4: Hand off for merge**

The feature branch `feature/client-canon-log-engine` is complete and green. Per CLAUDE.md §18, the human smoke-tests and merges `--no-ff` into `dev`, then deletes the branch. Claude does not merge or push here.

---

## Self-Review

**Spec coverage:**
- Decision 1 (GUT, headless): Task 1 vendors GUT v9.7.1 + `run_tests.sh`. ✔
- Decision 2 (logic layer only): no UI/HTTP/save-load task exists; noted as out-of-scope follow-ups. ✔
- Decision 3 (RefCounted typed classes, `to_dict`/`from_dict`): Tasks 2–3. ✔
- Decision 4 (invariants in the model; no client schema validator; api is authority): each entity owns its invariant (Task 2), container owns cap/dedup/stack (Task 3); Task 8 proves parity via invariant checks, not a schema port. ✔
- Decision 5 (Luck-centric game state; stat block data-only): Task 4 (`GameState`, `Luck`) + Task 6 rolls stats into state. ✔
- Decision 6 (mutators + tag extractor; no move validation): mutators Task 3, `TagExtractor` Task 7, move validation explicitly excluded. ✔
- Decision 7 (fat-but-decomposed): leaf entities + container + separate `NewGame`/`ContentDB`/`TagExtractor`. ✔
- §7 boundary (numeric luck never in log): enforced by `LogPlayer.to_dict` shape + `GameState` ownership; asserted in Tasks 2, 6, 8. ✔
- `recent_events` cap 5: `CanonLog.push_event` (Task 3), asserted Task 3 + 8. ✔
- Content resolution mirrors `api/app/content.py`: `ContentDB.unresolved_refs` (Task 5), same `"kind:id"` string format. ✔
- New-game construction ordering (resolve → constraints → roll → assemble): Task 6 mirrors the spec routine, incl. companion vs non-companion override split, situation→push_event trimming, inventory→state. ✔
- Deterministic Luck via injected RNG (§10): Task 4 tests, seeded RNG throughout Task 6/8. ✔

**Placeholder scan:** No TBD/TODO. The two `TUNABLE` markers (Luck bands/die, `_roll_stat`) are deliberate, flagged tuning constants with real working defaults — not unfinished code. ✔

**Type consistency:** `construct` returns `{ok, errors, log, state}` — consumed with those keys in Tasks 6 and 8. `unresolved_refs` returns `"location:…"`/`"item:…"` strings — asserted with those exact prefixes (Tasks 5, 6). `load_from`/`default_content_root`/`origin_path`/`load_json` names match across Tasks 5, 6, 8. `Luck.MIN/MAX/DRIFT`, `roll_base`, `drift`, `descriptor` consistent across Tasks 4, 6, 8. `to_dict`/`from_dict` present on every entity and consumed in round-trip (Task 8). ✔

**Deviations from spec (flag for reviewer):**
- `construct` returns a `{ok, errors, …}` result dict rather than raising — GDScript has no exceptions; this keeps failures testable. The spec described "fail loudly"; a populated `errors` array + null products is the loud, testable form.
- `LogLocation`/`Quest` id-regex validation `push_error`s but still assigns (does not hard-reject). The meaningful mutation invariants (clamp/cap/dedup/enum) are hard-enforced; id validity is a warning surface since ids originate from already-resolved content.

**Out of scope (later plans):** UI scenes, HTTP client + degraded-DM fallback, save/load + `schema_version` migration, move validation & apply, combat/stat consumers, content packaging for export, final Luck die/range + descriptor copy.