W103 (partial) — Companion Contracts and Ownership Reconciliation (#424)

* W103 (partial) — Companion Contracts and Ownership Reconciliation

Closes gaps found while reconciling W103's checklist against the tree and
three companion repos (GameOfLife, Platform, Adventures):

- W103.1: mirrors GameOfLife's StatusEffect and PendingEventResponse
  lifecycles (application/expiry, resolution) into 20-contract.md §2.3,
  the two confirmed missing of the fourteen GameOfLife S6/S7 lifecycles.
- W103.4: every retained campaign fixture now states in its own header
  that it is an unpublished regression fixture and names
  SubZeroDev.Adventures.Content as publication authority (20-contract.md
  §19); fixes a stale 04-core.md §19 citation (now an empty stub) in
  bulgaria-bureaucracy.freeze.test.ts.
- W103.5: records the public-vs-private package visibility decision as
  final in 90-decisions.md (mirrored into the generated OPEN-QUESTIONS.md
  copy by hand — no pwsh available locally to run the generator).
- W103.6: already resolved by prior recorded decisions (90-decisions.md,
  2026-08-10) — verified, no changes needed.
- W103.7: verified the kit sync landed with all four -Skip: guards
  intact; closed issue #365.

W103.2 and W103.3 remain open: Platform's vendored
@subzerodev/service-contract (0.5.0, pinned to engine 0.8.0) predates
W99's list_saves/branch_session/delete_save, and Adventures' HTTP layer
wraps SessionStore directly rather than routing through the generated
contract for catalog/save/branch/delete. Both require changes in
SubZeroDev.Platform, SubZeroDev.ServiceContract and SubZeroDev.Adventures
that this session has no push access to.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019hn3f2gYqEMoKbLPGFWbUK

* Regenerate human docs and stamp the guide after W103 edits

build/Test-Documentation.ps1 caught the generated-doc drift my previous
commit introduced (PowerShell wasn't available locally when I made that
commit, so I mirrored the OPEN-QUESTIONS.md edit by hand and missed the
simulation-kind pointer file and the guide's digest stamp). Installed
pwsh, ran the real generator instead of hand-editing further:

- design/10-simulation-kind.md and docs/docs/engine/10-simulation-kind.md
  regenerated from design/20-contract.md's new Status Effect / Pending
  Event Response lifecycle sections.
- docs/docs/guide.md restamped with the new design digest. Its content
  is unchanged: the guide already summarizes effect-expiry timing and
  pending-event blocking at the level "link back rather than duplicate
  detail" calls for, and links to Simulation Kind for the rest — the two
  new lifecycle sections are exactly that contract-level detail.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019hn3f2gYqEMoKbLPGFWbUK

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: The-Running-Dev

design/10-simulation-kind.md

@@ -20,10 +20,14 @@
 
 ### 2.3 Effects, Opportunities, and Scheduled Events
 
+#### Status Effect Lifecycle
+
 #### Opportunity Lifecycle
 
 #### Scheduled Event Lifecycle
 
+#### Pending Event Response Lifecycle
+
 ### 2.4 Goal State
 
 ### 2.5 Economy State

design/20-contract.md

@@ -3680,6 +3680,25 @@ fresh budget. `end_week`, and any `plan.add` other than `respond_to_event`, refu
 `PendingEventResponse` remains unaddressed by the current plan — `event_response_pending`
 (§10, W94).
 
+#### Status Effect Lifecycle
+
+**Application.** A `StatusEffect` is inserted into `activeEffects` by whichever resolver grants
+it — an item's own effects syncing with `activeEffects` on every resolution (`sourceKind:
+"item"`), an event outcome (`sourceKind: "event"`), or any other source named by
+`StatusEffect.sourceKind`. Insertion goes through one shared function regardless of source:
+`stacking: "refresh"` drops any existing effect with the same `sourceId` before adding the new
+one; `stacking: "stack"` adds alongside whatever is already active. `appliedWeek` is stamped from
+the current week at insertion.
+
+**Expiry.** The `effects` step of start-of-week (§12.1), run immediately after the week
+increments and before any other system, removes every effect whose `expiresAtWeek` is strictly
+before the new week — an effect expiring in week 12 still applies throughout week 12 and is
+removed only once the new week moves past it, at the start of week 13. An effect with no
+`expiresAtWeek` is permanent and is never removed by this step; it persists until its own source
+is resynced or replaced (as item effects are, above). Expiry emits `effect.expired` (§11) per
+effect and produces no `StateChange` — there is nothing for a client to undo when a timer
+elapses.
+
 #### Opportunity Lifecycle
 
 **Generation**, three paths, all producing an `Opportunity` from an `OpportunityDefinition`
@@ -3753,6 +3772,18 @@ not implicit.
 > cancellation path: it fires regardless of anything that happens between scheduling and
 > firing. Content that wants a scheduled event to be cancellable must put it in a chain.
 
+#### Pending Event Response Lifecycle
+
+**Creation** is stated above: firing a `ScheduledEvent` (or a random roll) that carries choices
+queues a `PendingEventResponse` for presentation at the start of the following week.
+
+**Resolution.** A `respond_to_event` action naming the pending entry's id is its only removal
+path: the resolver removes that entry from `pendingEventResponses` as part of the same
+`StateChange` set that records the chosen `choiceId` and applies the choice's costs. There is no
+expiry — a `PendingEventResponse` has no `expiresAtWeek` field, and `end_week` and every other
+`plan.add` refuse outright while one is unaddressed (`event_response_pending`, §10), so it
+cannot be outlived by the calendar the way an `Opportunity` or `ScheduledEvent` can.
+
 ### 2.4 Goal State
 
 ```typescript

design/90-decisions.md

@@ -54,8 +54,15 @@ answer now lives — so a later reader finds the reasoning without re-opening th
 
 Settled as out of MVP scope. Listed so they resurface deliberately, not by accident.
 
-- **The engine package published *public*, and the plans specify private — tracked as
-  [issue #302](https://github.com/The-Running-Dev/SubZeroDev.GameEngine/issues/302).**
+- **Package visibility, decided: public.** `src/engine/package.json` carries no `"private"`
+  field and publishes to `npm.pkg.github.com`; [Engine Package](/docs/guide/engine-package)
+  states the choice is deliberate. `plans/39-world-graph-kind-programme.md` and
+  `plans/40-w41-engine-consumer-boundary.md` both specified private GitHub Packages at the
+  time they were written and are annotated in place ("What shipped did not honour this") —
+  left as historical record of the original plan rather than rewritten, since a plan
+  document records intent at the time, not current fact. This is the final answer;
+  [issue #302](https://github.com/The-Running-Dev/SubZeroDev.GameEngine/issues/302) tracked
+  deciding it and is closed by this entry.
 - **Provisional simulation numbers** — drift rates, scenario economics, `demandBand`
   thresholds, housing-quality formula, travel costs. Need a balancing pass once the sim
   harness runs. Tracked as [issue #267](https://github.com/The-Running-Dev/SubZeroDev.GameEngine/issues/267).

docs/docs/engine/10-simulation-kind.md

@@ -399,6 +399,25 @@ fresh budget. `end_week`, and any `plan.add` other than `respond_to_event`, refu
 `PendingEventResponse` remains unaddressed by the current plan — `event_response_pending`
 (§10, W94).
 
+#### Status Effect Lifecycle
+
+**Application.** A `StatusEffect` is inserted into `activeEffects` by whichever resolver grants
+it — an item's own effects syncing with `activeEffects` on every resolution (`sourceKind:
+"item"`), an event outcome (`sourceKind: "event"`), or any other source named by
+`StatusEffect.sourceKind`. Insertion goes through one shared function regardless of source:
+`stacking: "refresh"` drops any existing effect with the same `sourceId` before adding the new
+one; `stacking: "stack"` adds alongside whatever is already active. `appliedWeek` is stamped from
+the current week at insertion.
+
+**Expiry.** The `effects` step of start-of-week (§12.1), run immediately after the week
+increments and before any other system, removes every effect whose `expiresAtWeek` is strictly
+before the new week — an effect expiring in week 12 still applies throughout week 12 and is
+removed only once the new week moves past it, at the start of week 13. An effect with no
+`expiresAtWeek` is permanent and is never removed by this step; it persists until its own source
+is resynced or replaced (as item effects are, above). Expiry emits `effect.expired` (§11) per
+effect and produces no `StateChange` — there is nothing for a client to undo when a timer
+elapses.
+
 #### Opportunity Lifecycle
 
 **Generation**, three paths, all producing an `Opportunity` from an `OpportunityDefinition`
@@ -472,6 +491,18 @@ not implicit.
 > cancellation path: it fires regardless of anything that happens between scheduling and
 > firing. Content that wants a scheduled event to be cancellable must put it in a chain.
 
+#### Pending Event Response Lifecycle
+
+**Creation** is stated above: firing a `ScheduledEvent` (or a random roll) that carries choices
+queues a `PendingEventResponse` for presentation at the start of the following week.
+
+**Resolution.** A `respond_to_event` action naming the pending entry's id is its only removal
+path: the resolver removes that entry from `pendingEventResponses` as part of the same
+`StateChange` set that records the chosen `choiceId` and applies the choice's costs. There is no
+expiry — a `PendingEventResponse` has no `expiresAtWeek` field, and `end_week` and every other
+`plan.add` refuse outright while one is unaddressed (`event_response_pending`, §10), so it
+cannot be outlived by the calendar the way an `Opportunity` or `ScheduledEvent` can.
+
 ### 2.4 Goal State
 
 ```typescript

docs/docs/engine/OPEN-QUESTIONS.md

@@ -44,8 +44,15 @@ answer now lives — so a later reader finds the reasoning without re-opening th
 
 Settled as out of MVP scope. Listed so they resurface deliberately, not by accident.
 
-- **The engine package published *public*, and the plans specify private — tracked as
-  [issue #302](https://github.com/The-Running-Dev/SubZeroDev.GameEngine/issues/302).**
+- **Package visibility, decided: public.** `src/engine/package.json` carries no `"private"`
+  field and publishes to `npm.pkg.github.com`; [Engine Package](/docs/guide/engine-package)
+  states the choice is deliberate. `plans/39-world-graph-kind-programme.md` and
+  `plans/40-w41-engine-consumer-boundary.md` both specified private GitHub Packages at the
+  time they were written and are annotated in place ("What shipped did not honour this") —
+  left as historical record of the original plan rather than rewritten, since a plan
+  document records intent at the time, not current fact. This is the final answer;
+  [issue #302](https://github.com/The-Running-Dev/SubZeroDev.GameEngine/issues/302) tracked
+  deciding it and is closed by this entry.
 - **Provisional simulation numbers** — drift rates, scenario economics, `demandBand`
   thresholds, housing-quality formula, travel costs. Need a balancing pass once the sim
   harness runs. Tracked as [issue #267](https://github.com/The-Running-Dev/SubZeroDev.GameEngine/issues/267).

docs/docs/guide.md

@@ -3,7 +3,7 @@ sidebar_position: 1
 sidebar_label: Developer Guide
 ---
 
-<!-- design-digest: c3d848ee9ce39ef41deb218339116cf62c2e3ccd9be4c4fb7a1d283519d9f625 -->
+<!-- design-digest: 515dcce1c756dbbb090a3a2bfef3abac13a039667fae94ae51fcae8bbbbe8edd -->
 
 > Generated from `design/` by `/make-human-docs`. Do not edit by hand — edit the
 > design docs and regenerate. `/reconcile` reports when this has gone stale.

src/engine/src/campaigns/bulgaria-bureaucracy.bg.ts

@@ -8,6 +8,9 @@
  * text), `buildStoryGraphCampaign` on this source produces byte-identical `content` to
  * the English build — proven in `bulgaria-bureaucracy.locale.test.ts` — and the two
  * differ only in the `strings` table each build produces.
+ *
+ * Unpublished regression fixture, not a publication source: `SubZeroDev.Adventures.Content`
+ * owns canonical narrative source and publication (`20-contract.md` §19).
  */
 
 import type { BuiltCampaign } from "../core/registry/types.js";

src/engine/src/campaigns/bulgaria-bureaucracy.broken.ts

@@ -10,6 +10,9 @@
  * the shape it emits has no `auto`-kind node left to mutate, so the two fixtures that
  * used to target one now target an equivalent `choice`/`random` node instead. Each
  * fixture's Tier and code are unchanged; only which node stands in for the mutation is.
+ *
+ * Unpublished regression fixture, not a publication source: `SubZeroDev.Adventures.Content`
+ * owns canonical narrative source and publication (`20-contract.md` §19).
  */
 
 import type { ChoiceNodeSource, RandomNodeSource } from "../kinds/story-graph/source.js";

src/engine/src/campaigns/bulgaria-bureaucracy.freeze.test.ts

@@ -1,6 +1,7 @@
 /**
  * The Bureaucracy campaign is frozen regression evidence, not a publication source (W74a,
- * `design/30-slices.md`; `02-architecture.md` §13; `04-core.md` §19). Today
+ * `design/30-slices.md`; `02-architecture.md` §13; `20-contract.md` §19 — `SubZeroDev.
+ * Adventures.Content` owns canonical narrative source and publication). Today
  * `bulgaria-bureaucracy.ts`/`.bg.ts` are both the replay oracle's baseline and a shipped
  * publication, so an edit made for the story's sake — a corrected typo, a rebalanced stat —
  * silently moves the baseline everything else is measured against, and the move only shows

src/engine/src/campaigns/bulgaria-bureaucracy.ts

@@ -1,3 +1,10 @@
+/**
+ * Content — "The Bureaucracy" (W15, `design/30-slices.md`).
+ *
+ * Unpublished regression fixture, not a publication source: `SubZeroDev.Adventures.Content`
+ * owns canonical narrative source and publication (`20-contract.md` §19).
+ */
+
 import type { BuiltCampaign } from "../core/registry/types.js";
 import type { CommandResult } from "../core/kernel/reasons.js";
 import type { StoryGraphCampaignSource } from "../kinds/story-graph/source.js";