# Client HTTP Loop (M2) 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:** Ship the first end-to-end vertical slice — a running Godot client posts its canon log to `/dm/narrate`, shows the returned prose on screen, harvests `[FACT:]` tags into its own log, and degrades to an authored fallback line on any failure.

**Architecture:** A pure `RefCounted` `DmService` owns all loop logic (build request body, parse the response, choose the fallback, harvest facts) behind a small `DmTransport` seam. The real `HttpTransport` wraps Godot's `HTTPRequest` Node; a `FakeDmTransport` double drives the service in headless GUT tests. A throwaway harness scene wires the real transport to a button and a label so a human can see prose. Facts are returned by `narrate()` and applied to the log by the caller — code owns the state mutation (charter §2).

**Tech Stack:** Godot 4.7, GDScript, GUT (headless test runner). No new dependencies. No autoloads.

Spec: `docs/superpowers/specs/2026-07-10-client-http-loop-design.md`.

## Global Constraints

Every task's requirements implicitly include this section.

- **Language/style:** GDScript. Pure classes are `class_name X extends RefCounted`. Follow the existing entity idiom (`client/scripts/canon_log/party_member.gd`): `_init` takes `p_`-prefixed args with defaults; value objects expose plain fields.
- **Client holds only the base URL** — never an API key, never a model name (charter §4).
- **Request/response contract (server, already live):** POST `/dm/narrate`, body exactly `{"canon_log": <log.to_dict()>}`. Success is **only** HTTP `200` with a dict body containing a `"prose"` key. `502` → `{"detail":{"model_error":…}}`; `422` → `{"detail":{"canon_log_errors":[…]}}`. Any non-200, transport failure, or malformed 200 → the fallback line. **No client-side retry.**
- **Harvest facts only.** The narrate loop harvests `[FACT:]` tags and nothing else; stray `[ADJUST_DISPOSITION]`/`[MOVE]` are dropped (they belong to the NPC role). Facts are harvested only on a real 200.
- **`narrate()` returns, it does not mutate.** It returns a `NarrateResult`; the caller applies facts via `CanonLog.add_fact(...)`.
- **Fallback content home:** `client/content/fallback/narrator.json` (renderer owns the file's home — root `/content` is server/authoring). The JSON is `{"narrator": [<lines>]}`. The library's hardcoded last-resort constant must be a **different string** from the authored line so tests can tell "loaded from file" from "fell back".
- **Base URL:** default `http://localhost:8000`, overridable via `ProjectSettings` key `coc_rpg/proxy_base_url`.
- **Naming (two deliberate departures from the spec's prose):**
  - The `NarrateResult` fallback constructor is `NarrateResult.fallback(line)`, **not** `.degraded(...)` — GDScript shares one namespace for members and methods, so a `degraded()` method would clash with the `degraded` field.
  - `DmTransport.post_json` base returns `DmResponse.failed("transport not implemented")` and `push_error`s, rather than `assert()` — GUT cannot catch a Godot `assert()`, so the not-implemented path must be a testable return value.
- **Tests:** GUT, `extends "res://addons/gut/test.gd"`, files under `client/tests/unit/` (the only dir GUT scans, per `.gutconfig.json`). Test doubles live under `client/tests/doubles/` (a sibling dir GUT does **not** scan). Run headless from `client/`:
  - Whole suite: `./run_tests.sh`
  - One file: `./run_tests.sh -gtest=res://tests/unit/<file>.gd`
  - `run_tests.sh` runs `godot --headless --import` first, so new `class_name` scripts resolve.
- **Untested-by-nature:** `HttpTransport` (needs a live `HTTPRequest` Node + server) and the harness scene are verified by reading + a by-hand live smoke against a running proxy — not by the unit suite. This parallels the server's `--run-live` gated boundary.
- **Git (charter §18):** all work on branch `feature/client-http-loop`, cut from `dev`. Commit after every task.

---

### Task 1: Net primitives — `DmResponse`, `NarrateResult`, `DmTransport`, `ProxyConfig`

The value/interface layer the service is built from. All pure, all headless-testable.

**Files:**
- Create: `client/scripts/net/dm_response.gd`
- Create: `client/scripts/net/narrate_result.gd`
- Create: `client/scripts/net/dm_transport.gd`
- Create: `client/scripts/net/proxy_config.gd`
- Test: `client/tests/unit/test_net_primitives.gd`

**Interfaces:**
- Consumes: nothing (leaf layer).
- Produces:
  - `DmResponse` — fields `status:int`, `body` (Variant: parsed JSON dict or `null`), `transport_ok:bool`, `error:String`. Static ctors `DmResponse.ok(status:int, body) -> DmResponse`, `DmResponse.failed(error:String) -> DmResponse`.
  - `NarrateResult` — fields `display_text:String`, `facts:Array`, `degraded:bool`. Ctor `NarrateResult.new(display_text:="", facts:=[], degraded:=false)`. Static ctor `NarrateResult.fallback(line:String) -> NarrateResult`.
  - `DmTransport` — base with coroutine `post_json(path:String, body:Dictionary) -> DmResponse`; base returns `DmResponse.failed("transport not implemented")`.
  - `ProxyConfig` — `const SETTING := "coc_rpg/proxy_base_url"`, `const DEFAULT := "http://localhost:8000"`, static `base_url() -> String`.

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

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

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

const DmResponse = preload("res://scripts/net/dm_response.gd")
const NarrateResult = preload("res://scripts/net/narrate_result.gd")
const DmTransport = preload("res://scripts/net/dm_transport.gd")
const ProxyConfig = preload("res://scripts/net/proxy_config.gd")


func test_dm_response_ok():
	var r = DmResponse.ok(200, {"prose": "hi"})
	assert_eq(r.status, 200)
	assert_true(r.transport_ok)
	assert_eq(r.body, {"prose": "hi"})
	assert_eq(r.error, "")


func test_dm_response_failed():
	var r = DmResponse.failed("boom")
	assert_false(r.transport_ok)
	assert_eq(r.status, 0)
	assert_eq(r.body, null)
	assert_eq(r.error, "boom")


func test_narrate_result_basic():
	var r = NarrateResult.new("text", ["a"], false)
	assert_eq(r.display_text, "text")
	assert_eq(r.facts, ["a"])
	assert_false(r.degraded)


func test_narrate_result_fallback():
	var r = NarrateResult.fallback("cold chamber")
	assert_eq(r.display_text, "cold chamber")
	assert_eq(r.facts, [])
	assert_true(r.degraded)


func test_transport_base_returns_not_implemented():
	var t = DmTransport.new()
	var r = await t.post_json("/x", {})
	assert_false(r.transport_ok)
	assert_eq(r.error, "transport not implemented")


func test_proxy_config_default():
	ProjectSettings.set_setting(ProxyConfig.SETTING, null)
	assert_eq(ProxyConfig.base_url(), ProxyConfig.DEFAULT)


func test_proxy_config_override():
	ProjectSettings.set_setting(ProxyConfig.SETTING, "http://example.test:9000")
	assert_eq(ProxyConfig.base_url(), "http://example.test:9000")
	ProjectSettings.set_setting(ProxyConfig.SETTING, null)
```

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

Run: `cd client && ./run_tests.sh -gtest=res://tests/unit/test_net_primitives.gd`
Expected: FAIL — GUT reports a load/parse error because the four preloaded scripts do not exist yet.

- [ ] **Step 3: Implement the four primitives**

Create `client/scripts/net/dm_response.gd`:

```gdscript
class_name DmResponse
extends RefCounted
## The raw outcome of one HTTP attempt, independent of any game meaning.
## `status` is 0 when the transport never reached the server; `body` is the
## parsed JSON dict, or null when the body was absent or not JSON.

var status: int
var body                      # Variant: parsed JSON (Dictionary) or null
var transport_ok: bool
var error: String


func _init(p_status := 0, p_body = null, p_transport_ok := false, p_error := "") -> void:
	status = p_status
	body = p_body
	transport_ok = p_transport_ok
	error = p_error


static func ok(p_status: int, p_body) -> DmResponse:
	return DmResponse.new(p_status, p_body, true, "")


static func failed(p_error: String) -> DmResponse:
	return DmResponse.new(0, null, false, p_error)
```

Create `client/scripts/net/narrate_result.gd`:

```gdscript
class_name NarrateResult
extends RefCounted
## The game-meaningful result of one narrate call. `facts` are the [FACT:]
## strings the caller applies to the canon log; empty when degraded.

var display_text: String
var facts: Array
var degraded: bool


func _init(p_display_text := "", p_facts := [], p_degraded := false) -> void:
	display_text = p_display_text
	facts = p_facts
	degraded = p_degraded


static func fallback(line: String) -> NarrateResult:
	return NarrateResult.new(line, [], true)
```

Create `client/scripts/net/dm_transport.gd`:

```gdscript
class_name DmTransport
extends RefCounted
## The network seam. DmService talks to this, never to HTTPRequest directly, so
## the loop logic is testable with an injected fake. Concrete transports
## override post_json. The base returns a failed response (rather than assert())
## so a missing override is a loud, catchable failure in tests.

func post_json(_path: String, _body: Dictionary) -> DmResponse:
	push_error("DmTransport.post_json must be overridden")
	return DmResponse.failed("transport not implemented")
```

Create `client/scripts/net/proxy_config.gd`:

```gdscript
class_name ProxyConfig
extends RefCounted
## The client's one piece of network config: the proxy base URL. Never a key,
## never a model name (charter §4). Overridable per environment via project
## settings; defaults to the dev proxy.

const SETTING := "coc_rpg/proxy_base_url"
const DEFAULT := "http://localhost:8000"


static func base_url() -> String:
	var v = ProjectSettings.get_setting(SETTING, DEFAULT)
	var s := str(v)
	return s if s != "" else DEFAULT
```

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

Run: `cd client && ./run_tests.sh -gtest=res://tests/unit/test_net_primitives.gd`
Expected: PASS — 7/7 passing, 0 errors.

- [ ] **Step 5: Commit**

```bash
git add client/scripts/net/dm_response.gd client/scripts/net/narrate_result.gd client/scripts/net/dm_transport.gd client/scripts/net/proxy_config.gd client/tests/unit/test_net_primitives.gd
git commit -m "feat(client): net primitives — DmResponse, NarrateResult, DmTransport, ProxyConfig"
```

---

### Task 2: `FallbackLibrary` + authored fallback content

Loads the authored §13 fallback line; falls back to a hardcoded constant if the file is missing or malformed (the fallback has a fallback — the player must never see an error).

**Files:**
- Create: `client/content/fallback/narrator.json`
- Create: `client/scripts/net/fallback_library.gd`
- Test: `client/tests/unit/test_fallback_library.gd`

**Interfaces:**
- Consumes: nothing.
- Produces: `FallbackLibrary` — ctor `FallbackLibrary.new(path := FallbackLibrary.PATH)`; method `narrator_line() -> String`; `const PATH := "res://content/fallback/narrator.json"`; `const LAST_RESORT := "The chamber is cold. Something waits in the dark."`

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

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

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

const FallbackLibrary = preload("res://scripts/net/fallback_library.gd")


func test_loads_authored_line_from_default_file():
	var lib = FallbackLibrary.new()
	# The authored line is distinct from LAST_RESORT, so a match proves the file was read.
	assert_ne(lib.narrator_line(), FallbackLibrary.LAST_RESORT)
	assert_true(lib.narrator_line().length() > 0)


func test_missing_file_uses_last_resort():
	var lib = FallbackLibrary.new("res://content/fallback/does_not_exist.json")
	assert_eq(lib.narrator_line(), FallbackLibrary.LAST_RESORT)


func test_malformed_file_uses_last_resort():
	var path := "user://bad_fallback.json"
	var f := FileAccess.open(path, FileAccess.WRITE)
	f.store_string("{ this is not valid json")
	f.close()
	var lib = FallbackLibrary.new(path)
	assert_eq(lib.narrator_line(), FallbackLibrary.LAST_RESORT)


func test_empty_list_uses_last_resort():
	var path := "user://empty_fallback.json"
	var f := FileAccess.open(path, FileAccess.WRITE)
	f.store_string('{"narrator": []}')
	f.close()
	var lib = FallbackLibrary.new(path)
	assert_eq(lib.narrator_line(), FallbackLibrary.LAST_RESORT)
```

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

Run: `cd client && ./run_tests.sh -gtest=res://tests/unit/test_fallback_library.gd`
Expected: FAIL — load/parse error, `fallback_library.gd` does not exist.

- [ ] **Step 3: Write the authored content**

Create `client/content/fallback/narrator.json` (Narrator voice per §3 — dry, gritty not grim, never winks; distinct from `LAST_RESORT`):

```json
{
  "narrator": [
    "The rain keeps on. The room ahead is dark and colder than it should be, and whatever is in it has been there a while."
  ]
}
```

- [ ] **Step 4: Write minimal implementation**

Create `client/scripts/net/fallback_library.gd`:

```gdscript
class_name FallbackLibrary
extends RefCounted
## Authored degraded-DM fallback text (charter §13). The client shows one of
## these lines on ANY failure, in the Narrator's voice — never an error. If the
## content file is missing or malformed the library returns a hardcoded
## constant, so the fallback itself cannot fail.

const PATH := "res://content/fallback/narrator.json"
const LAST_RESORT := "The chamber is cold. Something waits in the dark."

var _lines: Array = []


func _init(path := PATH) -> void:
	_lines = _load(path)


func narrator_line() -> String:
	return str(_lines[0]) if not _lines.is_empty() else LAST_RESORT


static func _load(path: String) -> Array:
	if not FileAccess.file_exists(path):
		return []
	var text := FileAccess.get_file_as_string(path)
	var data = JSON.parse_string(text)
	if typeof(data) != TYPE_DICTIONARY:
		return []
	var lines = data.get("narrator", [])
	return lines if typeof(lines) == TYPE_ARRAY else []
```

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

Run: `cd client && ./run_tests.sh -gtest=res://tests/unit/test_fallback_library.gd`
Expected: PASS — 4/4 passing.

- [ ] **Step 6: Commit**

```bash
git add client/content/fallback/narrator.json client/scripts/net/fallback_library.gd client/tests/unit/test_fallback_library.gd
git commit -m "feat(client): FallbackLibrary + authored narrator fallback (§13)"
```

---

### Task 3: `DmService` core + `FakeDmTransport` double

The heart of the slice: build the request, branch on the response, harvest facts, choose the fallback. Every branch is covered headless by injecting a fake transport.

**Files:**
- Create: `client/scripts/net/dm_service.gd`
- Create: `client/tests/doubles/fake_transport.gd`
- Test: `client/tests/unit/test_dm_service.gd`

**Interfaces:**
- Consumes: `DmResponse`, `NarrateResult`, `DmTransport` (Task 1); `FallbackLibrary` (Task 2); existing `CanonLog` (`to_dict()`, `add_fact()`) and `TagExtractor` (`extract(prose) -> {clean_text, facts, …}`).
- Produces: `DmService` — ctor `DmService.new(transport: DmTransport, fallback: FallbackLibrary)`; coroutine `narrate(canon_log: CanonLog) -> NarrateResult`.
- Produces (test double): `FakeDmTransport extends DmTransport` — `set_response(resp: DmResponse)`, records `last_path: String`, `last_body: Dictionary`.

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

Create `client/tests/doubles/fake_transport.gd`:

```gdscript
extends "res://scripts/net/dm_transport.gd"
## Test double for DmTransport. Returns a canned DmResponse and records the last
## call so tests can assert what the service posted. post_json needs no real
## async — awaiting a plain return value resolves immediately, so the same await
## call site in DmService drives both the real and the fake transport.

var _canned
var last_path: String
var last_body: Dictionary


func set_response(resp) -> void:
	_canned = resp


func post_json(path: String, body: Dictionary) -> DmResponse:
	last_path = path
	last_body = body
	return _canned
```

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

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

const DmService = preload("res://scripts/net/dm_service.gd")
const DmResponse = preload("res://scripts/net/dm_response.gd")
const FallbackLibrary = preload("res://scripts/net/fallback_library.gd")
const FakeDmTransport = preload("res://tests/doubles/fake_transport.gd")

var _fallback


func before_each():
	# Point the library at a missing file so narrator_line() is deterministically
	# LAST_RESORT — the degraded assertions don't depend on the authored content.
	_fallback = FallbackLibrary.new("res://content/fallback/does_not_exist.json")


func _log() -> CanonLog:
	return CanonLog.new()


func _service_for(resp) -> Dictionary:
	var t = FakeDmTransport.new()
	t.set_response(resp)
	return {"svc": DmService.new(t, _fallback), "transport": t}


func test_success_strips_tags_and_harvests_facts():
	var body := {"prose": "The docks reek of tar. [FACT: the eastern bridge is out]"}
	var pair := _service_for(DmResponse.ok(200, body))
	var r = await pair["svc"].narrate(_log())
	assert_false(r.degraded)
	assert_eq(r.display_text, "The docks reek of tar.")
	assert_eq(r.facts, ["the eastern bridge is out"])


func test_success_posts_canon_log_to_narrate_path():
	var pair := _service_for(DmResponse.ok(200, {"prose": "x"}))
	await pair["svc"].narrate(_log())
	assert_eq(pair["transport"].last_path, "/dm/narrate")
	assert_true(pair["transport"].last_body.has("canon_log"))


func test_502_degrades_to_fallback_with_no_facts():
	var pair := _service_for(DmResponse.ok(502, {"detail": {"model_error": "boom"}}))
	var r = await pair["svc"].narrate(_log())
	assert_true(r.degraded)
	assert_eq(r.display_text, FallbackLibrary.LAST_RESORT)
	assert_eq(r.facts, [])


func test_422_degrades():
	var pair := _service_for(DmResponse.ok(422, {"detail": {"canon_log_errors": ["x"]}}))
	var r = await pair["svc"].narrate(_log())
	assert_true(r.degraded)


func test_transport_failure_degrades():
	var pair := _service_for(DmResponse.failed("connection refused"))
	var r = await pair["svc"].narrate(_log())
	assert_true(r.degraded)


func test_malformed_200_missing_prose_degrades():
	var pair := _service_for(DmResponse.ok(200, {"nope": 1}))
	var r = await pair["svc"].narrate(_log())
	assert_true(r.degraded)


func test_malformed_200_non_dict_body_degrades():
	var pair := _service_for(DmResponse.ok(200, null))
	var r = await pair["svc"].narrate(_log())
	assert_true(r.degraded)


func test_only_facts_harvested_dispositions_and_moves_dropped():
	var body := {"prose": "Hi [FACT: a] [ADJUST_DISPOSITION: +5] [MOVE: refuse()] bye"}
	var pair := _service_for(DmResponse.ok(200, body))
	var r = await pair["svc"].narrate(_log())
	assert_eq(r.facts, ["a"])
	assert_eq(r.display_text, "Hi bye")
```

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

Run: `cd client && ./run_tests.sh -gtest=res://tests/unit/test_dm_service.gd`
Expected: FAIL — load/parse error, `dm_service.gd` does not exist.

- [ ] **Step 3: Write minimal implementation**

Create `client/scripts/net/dm_service.gd`:

```gdscript
class_name DmService
extends RefCounted
## The client narrate loop (charter §2: the client owns the loop and consumes
## text). Posts the canon log to /dm/narrate through an injected transport,
## returns the prose to display and the [FACT:] tags to harvest. On ANY failure
## it returns an authored fallback line — never an error. It harvests facts
## only; the Narrator has no authority over disposition or moves, so those tags
## are dropped even if the model emits them (§6). narrate() does not mutate the
## log — the caller applies the returned facts, keeping the state write explicit.

var _transport: DmTransport
var _fallback: FallbackLibrary


func _init(transport: DmTransport, fallback: FallbackLibrary) -> void:
	_transport = transport
	_fallback = fallback


func narrate(canon_log: CanonLog) -> NarrateResult:
	var resp: DmResponse = await _transport.post_json(
		"/dm/narrate", {"canon_log": canon_log.to_dict()})
	if not resp.transport_ok or resp.status != 200 \
			or typeof(resp.body) != TYPE_DICTIONARY or not resp.body.has("prose"):
		return NarrateResult.fallback(_fallback.narrator_line())
	var extracted := TagExtractor.extract(str(resp.body["prose"]))
	return NarrateResult.new(extracted["clean_text"], extracted["facts"], false)
```

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

Run: `cd client && ./run_tests.sh -gtest=res://tests/unit/test_dm_service.gd`
Expected: PASS — 8/8 passing.

- [ ] **Step 5: Run the whole suite to confirm no regressions**

Run: `cd client && ./run_tests.sh`
Expected: PASS — all prior tests plus the three new files green, 0 errors.

- [ ] **Step 6: Commit**

```bash
git add client/scripts/net/dm_service.gd client/tests/doubles/fake_transport.gd client/tests/unit/test_dm_service.gd
git commit -m "feat(client): DmService narrate loop + FakeDmTransport (all branches tested)"
```

---

### Task 4: `HttpTransport` — the real transport (untested shim)

Wraps a live `HTTPRequest` Node and maps its async signal onto a `DmResponse`. No unit test: it needs a tree Node and a server. It is verified by reading here and by the live smoke in Task 5.

**Files:**
- Create: `client/scripts/net/http_transport.gd`

**Interfaces:**
- Consumes: `DmResponse` (Task 1), `ProxyConfig` (Task 1). Constructed with an `HTTPRequest` Node the owner has already added to the scene tree.
- Produces: `HttpTransport extends DmTransport` — ctor `HttpTransport.new(http: HTTPRequest)`; overrides `post_json(path, body) -> DmResponse`.

- [ ] **Step 1: Write the implementation**

Create `client/scripts/net/http_transport.gd`:

```gdscript
extends "res://scripts/net/dm_transport.gd"
## The real transport: wraps an HTTPRequest Node the owner added to the tree.
## This is the one untested shim in the slice — it needs a live Node and a
## server, so it is verified by reading and by the harness live smoke, the same
## way the server's HTTP boundary is covered only by its gated --run-live test.
## A non-2xx status is NOT an error here; it is a normal DmResponse the service
## interprets. Only a transport-level failure (no response) yields failed().

const ProxyConfig = preload("res://scripts/net/proxy_config.gd")
const DmResponse = preload("res://scripts/net/dm_response.gd")

var _http: HTTPRequest


func _init(http: HTTPRequest) -> void:
	_http = http


func post_json(path: String, body: Dictionary) -> DmResponse:
	var url := ProxyConfig.base_url() + path
	var headers := ["Content-Type: application/json"]
	var payload := JSON.stringify(body)
	var err := _http.request(url, headers, HTTPClient.METHOD_POST, payload)
	if err != OK:
		return DmResponse.failed("request() failed to start: error %d" % err)
	# request_completed(result, response_code, headers, body) — awaiting a
	# multi-arg signal returns the args as an Array.
	var signal_args: Array = await _http.request_completed
	var result: int = signal_args[0]
	var response_code: int = signal_args[1]
	var raw: PackedByteArray = signal_args[3]
	if result != HTTPRequest.RESULT_SUCCESS:
		return DmResponse.failed("transport result %d" % result)
	var parsed = JSON.parse_string(raw.get_string_from_utf8())  # null if not JSON
	return DmResponse.ok(response_code, parsed)
```

- [ ] **Step 2: Verify it parses**

Run: `cd client && godot --headless --import`
Expected: import completes with no parse/script errors mentioning `http_transport.gd`. (There is no unit test for this file by design; the review and Task 5's live smoke cover it.)

- [ ] **Step 3: Commit**

```bash
git add client/scripts/net/http_transport.gd
git commit -m "feat(client): HttpTransport — real HTTPRequest transport (untested shim)"
```

---

### Task 5: Throwaway harness scene + live-smoke doc

The "human sees prose" surface: a button, a label, a status line. Builds the transport → service, posts a hand-built valid canon log, shows the prose, applies harvested facts. Disposable — the real UI is a later wireframe. Verified by hand against a running proxy.

**Files:**
- Create: `client/scripts/harness/narrate_harness.gd`
- Create: `client/scenes/narrate_harness.tscn`
- Modify: `client/docs/README.md` (append a "Narrate live smoke" section)

**Interfaces:**
- Consumes: `HttpTransport` (Task 4), `DmService` (Task 3), `FallbackLibrary` (Task 2); existing `CanonLog`, `LogPlayer`, `LogLocation`, `PartyMember`, `Quest`, `Humiliation`.
- Produces: a runnable scene; no code other tasks depend on.

- [ ] **Step 1: Write the harness script**

Create `client/scripts/harness/narrate_harness.gd`. The fixture mirrors the proven-valid `api/tests/fixtures/canon_log_valid.json` so the request passes the server's schema check and the prose is grounded:

```gdscript
extends Control
## Throwaway M2 harness — the first on-screen generated prose. Wires the real
## transport to a button and a label. NOT the game UI (a later wireframe owns
## that). Run this scene directly (F6) with the proxy + Ollama up; see the live
## smoke steps in client/docs/README.md.

const DmService = preload("res://scripts/net/dm_service.gd")
const HttpTransport = preload("res://scripts/net/http_transport.gd")
const FallbackLibrary = preload("res://scripts/net/fallback_library.gd")

var _service: DmService
var _log: CanonLog
var _label: RichTextLabel
var _status: Label
var _button: Button


func _ready() -> void:
	var http := HTTPRequest.new()
	add_child(http)
	_service = DmService.new(HttpTransport.new(http), FallbackLibrary.new())
	_log = _build_scene_log()

	var vbox := VBoxContainer.new()
	vbox.set_anchors_preset(Control.PRESET_FULL_RECT)
	vbox.add_theme_constant_override("separation", 12)
	add_child(vbox)

	_button = Button.new()
	_button.text = "Narrate this scene"
	_button.pressed.connect(_on_narrate_pressed)
	vbox.add_child(_button)

	_label = RichTextLabel.new()
	_label.fit_content = true
	_label.custom_minimum_size = Vector2(640, 320)
	vbox.add_child(_label)

	_status = Label.new()
	vbox.add_child(_status)


func _on_narrate_pressed() -> void:
	_button.disabled = true
	_status.text = "…narrating…"
	var r := await _service.narrate(_log)
	_label.text = r.display_text
	for f in r.facts:
		_log.add_fact(f)
	_status.text = "facts harvested: %d%s" % [r.facts.size(), "   (degraded)" if r.degraded else ""]
	_button.disabled = false


func _build_scene_log() -> CanonLog:
	var log := CanonLog.new()
	log.player = LogPlayer.new("Aldric", "sellsword", "Fortune spits on you")
	log.set_location("greywater_docks", "the Greywater docks")
	log.party.append(PartyMember.new("brannoc_thane", "Brannoc Thane", 40))
	log.party.append(PartyMember.new("cadwyn_vell", "Cadwyn Vell", 15))
	log.push_event("Arrived at Greywater by barge before dawn")
	log.push_event("Brannoc recognised the harbourmaster and went quiet")
	log.add_fact("the eastern bridge out of Greywater is washed out")
	log.add_fact("the harbourmaster is named Oda Fenn")
	log.active_quests.append(Quest.new("find_the_ledger", "The Missing Ledger", "active", "Find who took Fenn's ledger"))
	log.add_humiliation("h_0001", "vomited on a shrine step in front of a priest", 7, 3)
	return log
```

Argument orders are confirmed against the source: `Quest.new(id, name, status, objective)` (`client/scripts/canon_log/quest.gd:13`) and `CanonLog.add_humiliation(id, text, weight, turn)` (`client/scripts/canon_log/canon_log.gd:38`). Use them as written.

- [ ] **Step 2: Write the scene file**

Create `client/scenes/narrate_harness.tscn`. Minimal root + script (all children are built in `_ready`, so the scene needs no hand-authored node tree). Godot will assign a `uid` on first import; that is expected and fine to commit:

```
[gd_scene load_steps=2 format=3]

[ext_resource type="Script" path="res://scripts/harness/narrate_harness.gd" id="1_harness"]

[node name="NarrateHarness" type="Control"]
layout_mode = 3
anchors_preset = 15
anchor_right = 1.0
anchor_bottom = 1.0
script = ExtResource("1_harness")
```

- [ ] **Step 3: Verify it imports and parses**

Run: `cd client && godot --headless --import`
Expected: import completes with no script/scene errors mentioning `narrate_harness`. Then confirm the unit suite is still green: `./run_tests.sh` → all pass (the harness has no unit test; this step guards against a parse error leaking in).

- [ ] **Step 4: Document the live smoke**

Append to `client/docs/README.md`:

```markdown

## Narrate live smoke (M2 client HTTP loop)

The `narrate_harness` scene is a throwaway proof of the client → `/dm/narrate`
loop. It is not the game UI.

**Prereqs:** the proxy running and Ollama reachable.

1. Start the proxy: from `api/`, `uvicorn app.main:app --port 8000` (with the
   `.env` from `.env.example`; Ollama up at `OLLAMA_BASE_URL`).
2. In the Godot editor, open `res://scenes/narrate_harness.tscn` and run it (F6).
3. Click **Narrate this scene**. Expect grounded prose in the Narrator's voice
   (referencing Greywater / Brannoc / the washed-out bridge), tags stripped, and
   `facts harvested: N` with N ≥ 0.
4. **Degraded path:** stop the proxy and click again. Expect the authored
   fallback line and `(degraded)` in the status — never an error.

Override the proxy URL with the `coc_rpg/proxy_base_url` project setting.
```

- [ ] **Step 5: Commit**

```bash
git add client/scripts/harness/narrate_harness.gd client/scenes/narrate_harness.tscn client/docs/README.md
git commit -m "feat(client): throwaway narrate harness scene + live-smoke doc"
```

---

## Self-Review

**Spec coverage:**
- Data flow (spec) → Task 3 `DmService.narrate`. ✓
- `DmResponse` / `DmTransport` / `NarrateResult` / `ProxyConfig` (spec components) → Task 1. ✓
- `FallbackLibrary` + authored JSON + content-home rule → Task 2. ✓
- `HttpTransport` untested shim → Task 4. ✓
- Harness scene + live smoke → Task 5. ✓
- Facts-only harvest, degraded on every failure branch, returns-not-mutates → Task 3 tests. ✓
- Base URL default + override (§4) → Task 1 `ProxyConfig` tests. ✓
- Out-of-scope items (real UI, streaming, NPC moves, retry) → not implemented, as specified. ✓
- Follow-up (CLAUDE.md §16 note) → recorded in the spec's "Follow-ups"; not a task here (doc edit, deliberately deferred). ✓

**Placeholder scan:** No TBD/TODO. Every code step shows complete code. The one "confirm the signature before running" note (Task 5, `Quest.new`) is a real instruction with the known-good order given, not a placeholder.

**Type consistency:** `DmResponse.ok/failed`, `NarrateResult.new/fallback`, `DmTransport.post_json`, `FallbackLibrary.new/narrator_line/PATH/LAST_RESORT`, `DmService.new/narrate`, `HttpTransport.new`, `ProxyConfig.SETTING/DEFAULT/base_url` — all used consistently across tasks and match the Interfaces blocks. `FakeDmTransport.post_json` matches the `DmTransport` base signature. The `narrate()` return (`NarrateResult`) is consumed correctly by the harness.