Skip to content

Commit 5dc1bdd

Browse files
Correct 20-contract §19's list of /authoring exports (#366)
Carried over from [#316](#316), which was closed as superseded. This was the one part of that branch that had not landed independently. ## What was wrong `20-contract.md` §19 described `@the-running-dev/game-engine/authoring` as exporting: > generic content-registry builder, the story-graph source builder, the shared adventure builder and its migration helper … Two things are inaccurate against `src/engine/src/authoring.ts`: - The subpath exports `buildCampaign` — a **campaign** builder, from `core/registry/build.ts`. `buildContentRegistry` is not exported from `/authoring` at all, so a reader following §19 would go looking for a surface that is not there. - The adventure exports are three, not two: `buildAdventureCampaign`, `createAdventureSource`, `migrateV1AdventureState`. The sentence named the builder and the migration helper and dropped the source factory. `docs/docs/guide.md` carried the same drift in its own words ("the content-registry builder, the story-graph and adventure source builders and their migration helpers") and is corrected to match. ## What changed - `design/20-contract.md` §19 — the canonical edit, two lines. - `docs/docs/engine/04-core.md` — regenerated by `./build/ConvertTo-HumanDocumentation.ps1`, not hand-edited. - `docs/docs/guide.md` — the affected paragraph corrected and the design digest re-stamped with `-StampGuide`. Wording only. No type, signature, or export changes — the code was already right; the contract was describing it wrongly. ## Note on how the guide was regenerated `/make-human-docs` overwrites `guide.md` in full with no partial regeneration. For a two-noun correction in one paragraph of an 841-line file, a full rewrite would have produced a large unrelated diff on a branch scoped to one sentence, so the affected paragraph was corrected in place and the digest re-stamped. The gate that matters — `Test-Documentation.ps1`'s guide-digest check — passes either way, but the choice is recorded here rather than left to be inferred from the diff. ## Gates | Gate | Result | |---|---| | `./build/Test-Documentation.ps1` | pass — drift check across 18 generated engine pages, compatibility pointers and the guide; 125 Markdown files | | `npm run typecheck` | pass | | `npm run lint` | pass | | `npm test` | pass — 79 files, 1173 tests | | `git diff --check` | clean | **Did not run:** `./docs.ps1 -BuildOnly`, the production Docusaurus build. `docs.ps1` is not installed in this checkout, so it could not be run locally — the *Verify Documentation Build* check on this PR is the gate that covers it, and it should be read there rather than assumed from the above.
2 parents 24641e0 + 358d236 commit 5dc1bdd

3 files changed

Lines changed: 13 additions & 13 deletions

File tree

design/20-contract.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1539,8 +1539,8 @@ them, so a rename breaks old data.
15391539
15401540
The package root is the runtime contract. `@the-running-dev/game-engine/authoring` is the
15411541
separate author-time contract for repositories that own campaign source. It exports the
1542-
generic content-registry builder, the story-graph source builder, the shared adventure
1543-
builder and its migration helper, portable serialization and manifest digests, and
1542+
generic campaign builder, the story-graph source builder, the shared adventure builder with
1543+
its source factory and its migration helper, portable serialization and manifest digests, and
15441544
replay-runner types/functions. It is deliberately a
15451545
subpath: a runtime host must not import authored campaign source merely to play published
15461546
portable JSON.

docs/docs/engine/04-core.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1511,8 +1511,8 @@ them, so a rename breaks old data.
15111511
15121512
The package root is the runtime contract. `@the-running-dev/game-engine/authoring` is the
15131513
separate author-time contract for repositories that own campaign source. It exports the
1514-
generic content-registry builder, the story-graph source builder, the shared adventure
1515-
builder and its migration helper, portable serialization and manifest digests, and
1514+
generic campaign builder, the story-graph source builder, the shared adventure builder with
1515+
its source factory and its migration helper, portable serialization and manifest digests, and
15161516
replay-runner types/functions. It is deliberately a
15171517
subpath: a runtime host must not import authored campaign source merely to play published
15181518
portable JSON.

docs/docs/guide.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ sidebar_position: 1
33
sidebar_label: Developer Guide
44
---
55

6-
<!-- design-digest: 4cd4099867b95bef280462a7c52e0449d702b7b163867a2e29fc9fad84c3eab9 -->
6+
<!-- design-digest: 5a2c5126ec1504b8ee04110ce91843f08484d01673a4055edae77b9dc7e1b0dd -->
77

88
> Generated from `design/` by `/make-human-docs`. Do not edit by hand — edit the
99
> design docs and regenerate. `/reconcile` reports when this has gone stale.
@@ -130,14 +130,14 @@ manifest hosts fetch. This engine stays the authority for deterministic mechanic
130130
validation, and portable hydration.
131131

132132
The package root is for runtime hosts. A separate subpath, `/authoring`, is for repositories that
133-
own campaign source: it exports the content-registry builder, the story-graph and adventure source
134-
builders and their migration helpers, portable serialization and manifest-digest functions, and
135-
replay-runner types. Import from `/authoring` only when writing or publishing campaign content —
136-
a runtime host must never import authored campaign source merely to play already-published
137-
portable JSON. `toPortable` and the manifest-resolution digest are `/authoring`-only;
138-
`fromPortable` is root-only; the portable-campaign digest function is exported from both, because
139-
both a runtime host verifying fetched content and a publishing pipeline digesting source before it
140-
ships need it.
133+
own campaign source: it exports the generic campaign builder, the story-graph source builder, the
134+
adventure builder with its source factory and its migration helper, portable serialization and
135+
manifest-digest functions, and replay-runner types. Import from `/authoring` only when writing or
136+
publishing campaign content — a runtime host must never import authored campaign source merely to
137+
play already-published portable JSON. `toPortable` and the manifest-resolution digest are
138+
`/authoring`-only; `fromPortable` is root-only; the portable-campaign digest function is exported
139+
from both, because both a runtime host verifying fetched content and a publishing pipeline
140+
digesting source before it ships need it.
141141

142142
A handful of frozen campaigns still ship as package-root exports for compatibility. They are
143143
regression fixtures, not a publication source, and a later breaking release removes them from the

0 commit comments

Comments
 (0)