Ghostlight/docs/architecture/ghostlight-library-extraction-postmortem.md

# Ghostlight library extraction (L0) postmortem

Written 2026-09-16. Evidence: the cut map
(`ghostlight-library-extraction-cut.md`), the target
(`ghostlight-library-extraction.md`), commits in Ghostlight and gamecult-ops,
and the Soul reports recorded in the map.

## Summary

The world kernel moved out of the `ghostlight-dungeon` binary into the
`ghostlight` library crate, and Dungeon became a consumer across a public
boundary. Thirteen files (about 52k lines) moved by rename with no content
change. The boundary is sealed by admission: external code may build a
syntactically valid ID, digest or opportunity, and the kernel rejects every
one it did not issue, proven by rejection tests written as an external crate.
gamecult-ops' build commands run the library tests they would otherwise have
skipped.

State at writing: landed and pushed in both repos, Windows-verified. The Linux
release is Idunn's recipe run on Yggdrasil and has not been exercised; no
Windows result proves it. The operator owes nothing for L0.

## Scope and invariants

The target set seven invariants: sealed kernel at the crate boundary, no
behavior or schema change, no Dungeon concept in the library, dependencies
pointing one way, a working release path, unaffected external pins, and one
new crate with no feature matrix. Excluded: every library capability of plan
step 15 L1–L4, schema renames, the network path for outside consumers, and
deployment cutover.

Invariant 1 changed meaning during the migration (ruling Q1-9). It began as
"sealed items are unreachable from outside" and ended as "the kernel rejects
anything it did not issue", because the first reading was not true of the
code and could not be made true without a design change L0 excluded.

## Timeline

| Cut | Repo, commits | Soul passes | Notable finding |
|---|---|---|---|
| Map | Ghostlight `02bbf62`, `6ddabca` | — | Classifying the fixture tests found no kernel test to move; Q1-7 and Q1-8 followed |
| 1 | Ghostlight `108b691..f859d2c` | 1 | F1: public types deriving `Deserialize` are constructible from outside; the compile_fail tests pin names only |
| 2 | gamecult-ops `6aba281` | 1 | The specified assertion was vacuous (substring match); the acceptance path had an unlisted fourth site |
| 2 fix | gamecult-ops `803f2c7` | 1 | Exact-line pins prove presence, not execution (`if false`, `true \|\|`, heredoc) |
| Q1-9 | Ghostlight `7c1d1e9` | — | Operator ruled unforgeable admission |
| 1 fix | Ghostlight `a8d3377..2865ea7` | 1 | F3's premise was wrong; forgeries differed from real digests in length |
| S batch | Ghostlight `bde05de..af9c95a` | 1 | Case-insensitive and hex-only comparisons survived |
| T batch | Ghostlight `b14507c`, `ab95d78` | 1 | None |

## Structural delta

| Area | Estimate | Actual |
|---|---|---|
| Crate sources, including in-module tests | about +65 net | +1202 / −992, +210 net |
| Integration tests | not planned | +479 (`crates/ghostlight/tests/external_admission.rs`) |
| Manifests and lock | about +50 | +50 / −2 |
| Ghostlight recipe | about +6 | +10 / −5 |
| gamecult-ops | about +5 | +61 / −9 |

The source overrun has two causes. The single-minter scanner in
`crates/ghostlight-dungeon/src/app_session.rs` grew about 110 lines chasing
Soul's evasions, and it is still evadable (S4). The public boundary needed
roughly 90 more items than the map enumerated, each forced by a compile error
or a `private_interfaces` warning. The integration tests were not in the
estimate because Q1-9, which requires them, was ruled after it.

Deleted: `mod world;`, nine unused re-exports, the `cfg(test)` re-export
block, five inference fixtures, `fixture_controller_opportunities`, and
Dungeon's own principal evidence struct. Added: one library crate, a public
`pub use` boundary, port constructors, ten compile_fail doc-tests, the
external admission tests, and two Dungeon soul tests. Parked: nothing.
Features added: none. Binaries added: none.

## What Soul caught

- **Untested rulings.** Ruling Q1-4 said sealed constructors must be
  unreachable under every configuration. The code satisfied the letter
  (no feature gate) and missed the intent: `Deserialize` is a public
  constructor. Ten green compile_fail tests could not see it, and adding an
  ID-minting `Default` impl left all ten green. It would have failed as a
  false guarantee in any later review that trusted the target doc.
- **Tests pinning spelling, not behavior.** Every text scanner lost to a short
  evasion: the minter count to an alias, a subdirectory, a type alias and a
  function value; the gamecult-ops wiring test to a two-line deletion that
  reattached the pinned line to the wrong container; its fix to control flow
  around exact lines. Each would have let a real regression through with a
  green check.
- **Forgery shape.** Rejection tests that used short fake digests passed
  against a kernel comparing only length, only a prefix, all but the last
  character, case-insensitively, or only the hex after the label. Each would
  have admitted a digest the kernel never issued.
- **Spec errors.** The map's vacuous `require_text`, its unlisted acceptance
  site, its miscount of Dungeon tests, and Soul's own F3 premise (the two
  accessors it called uncalled are called) were all wrong, and all were
  caught before landing a fix built on them.
- **Unmeasured claims.** "No new package in `Cargo.lock`", "zero `fixture_`
  hits", "a guard that never fired", and a 13-warning ceiling nobody could
  reproduce.

## Operator corrections

- **Session Zero is Dungeon authority.** The first design placed a player
  flow on the kernel. Missing context: no document named which features
  belonged to the library and which to a consumer.
- **Focus was too narrow.** Focus as a set of subjects became a typed detail
  rule, a function from place to detail level. Missing context: Delvehold's
  constraints as a consumer; the design generalized from Dungeon alone.
- **Extract first.** The library capabilities were designed before the crate
  they belong to existed.
- **The titled elaborators** had been cut without an operator decision; the
  cut conflated a verifier with the lenses it verified.
- **Proportion.** Asked how much Q1-10 mattered, the operator said not at
  all. It was a tripwire against the project's own code, and Self should have
  defaulted it instead of posing it.

## Incidents

- **A Hands agent returned its private to-do list as its report** while its
  own background cargo job held the locks. Cost: one resume round. Rule:
  briefs now say to wait for long jobs and never end a turn with a to-do list.
- **A mutation run was invalidated by `git checkout`** reverting uncommitted
  fix code. Cost: two mutations rerun. Rule: run mutations against committed
  code, or restore with a diff rather than a checkout.
- **Cached no-op builds reported zero warnings.** Cargo replays warnings only
  when it rebuilds. Rule: measure warnings from a forced rebuild, and compare
  distinct messages by `cmp`.
- **A commit message described code replaced before commit** (`fac90e6`).
  Left in history; recorded in the map.
- **A pre-existing `cargo fmt --check` failure** across the library, found
  in passing.

## What worked

- Classifying tests before moving them. Q1-4's "move the tests" had nothing
  to move, and the classification turned a vague ruling into two concrete
  ones.
- Soul building an external scratch crate to break the seal. The serde route
  was invisible from inside the crate and to every doc-test.
- Holding map edits until Soul finished, so every Soul pass read a clean tree.
- Having Hands report spec discrepancies instead of redesigning: the vacuous
  assertion, the fourth acceptance site, the recovery_required collision.
- Parallel Hands in separate repos only when the second did not depend on the
  first landing.

## What to change in the pipeline

- **Brief Soul to attack constructibility, not names, on any sealed boundary.**
  Evidence: F1 on Cut 1, found only because the root agent added the serde
  route to the brief by hand.
- **Treat a text scanner as a tripwire with stated limits, never as proof of a
  semantic property.** Prefer a semantic tool (Clippy lints, the type system)
  or record the property as unenforced. Evidence: every scanner in L0 lost.
- **Rejection tests must use forgeries shaped like real values.** Evidence:
  S1 and the two survivors after it.
- **Default proportionate questions instead of asking.** A fork that guards
  only against the project's own code is a default with a recorded follow-up.
  Evidence: Q1-10.

## Open follow-ups

| Item | Owner | Where | Why it can wait |
|---|---|---|---|
| S4 minter scanner evadable; Clippy `disallowed-methods` recorded as the fix | Dungeon | `crates/ghostlight-dungeon/src/app_session.rs:523-668` | Guards only against the project's own code |
| S5 credential-name test splits on one literal marker | Dungeon | `crates/ghostlight-dungeon/src/runtime.rs:3584` | Same class as S4, pre-existing |
| S6 stable rustc does not enforce compile_fail error codes | Library | `crates/ghostlight/src/lib.rs:15-57` | Admission is proven by the external tests; codes need a snapshot tool |
| S2 world_id check redundant, S3 decline path unreachable from outside | Library | `lib.rs:4193`, `lib.rs:1603` | Redundant by construction and crate-private respectively |
| `ScopeDigest`, `WorkLane`, `ScopeComponents` public through public enums | Library | `KernelError`, `ControllerWorkCustody`, `NarrativeCheckpoint` | Closing them reshapes public enums, a design change |
| `cargo fmt --check` fails across the library | Library | `crates/ghostlight` | Pre-existing; formatting only |
| Recipe schema drift (`foundation.v0`, `controller_work.v3` against `consumer.v4`, `controller_work.v15`) | Deployment gate | `deployment/idunn/recipe.toml` | Changes no behavior in L0 |
| `build_provenance` not run by the recipe | Deployment gate | `deployment/idunn/recipe.toml` | A recipe change with its own reason |
| Redeploy of a sealed commit runs no tests; exact-line pins cannot see control flow; `set -e` unpinned; duplicate blocks pass; web container and Connector steps pinned by substring; 18-line option window | Deployment gate | `gamecult-ops/scripts/deploy-ghostlight-yggdrasil.sh`, `test-ghostlight-yggdrasil-wiring.sh` | Legacy actuator under a do-not-invoke warning, retired at the gate |
| Linux release unverified | Operator, via Idunn | Yggdrasil | Needs the deployment gate |