Updating a Server - flukeatzerocool/holonovel GitHub Wiki

Updating a Server

How-to. For builders with an existing Holonovel server. The specification has changed. Your server needs to follow — without losing your campaigns.

When to update

The specification (holonovel.md) is a living document. It improves — new requirements, hardened subsystems, bug fixes. Every change is recorded in the CHANGELOG.

You update when:

A spec revision changes a REQ your server implements
The CHANGELOG announces a subsystem you depend on has been hardened
The pre-push hook tells you the spec changed but the server wasn't updated
You want the latest verification and quality guarantees

Updates are incremental by design. The spec delta determines the scope. Full rebuilds have token and time costs; the builder prefers incremental updates when the delta is narrow. A full rebuild is only required when the ruleset changes, the extraction model changes, or the spec version changes.

Source: spec §1 (build model), spec §6.7 (REQ-098).

Fingerprint-scoped updates

The spec records two content fingerprints — one for the ruleset package format (REQ-420) and one for the user-data format (REQ-423). On update, the builder compares these against the server's current values. A changed ruleset-format fingerprint scopes the update to the ruleset packages (via the update-rulesets entry point, REQ-422); a changed data-format fingerprint scopes it to user-data migration (via the migrate-user-data entry point, REQ-424). Narrow deltas get narrow updates — the builder re-verifies only the surfaces the delta touched.

Source: spec §5.18 (REQ-420 through REQ-424), §6.7.

The update workflow

The Spec-driven Update workflow (§6.7, REQ-098) runs four phases:

1. Intake (§6.2)

The AI asks update-specific questions:

Where is the server to update?
How should the spec version delta be detected? (auto — compare DECISIONS.md to current spec)
Fetch the latest spec from repo before updating?

The AI fetches the latest holonovel.md from the repository URL recorded at build time. Fetch failure doesn't block — you can update against the local copy.

2. Gap audit

The AI compares your server against the current specification across six surfaces:

Surface	What's checked
Tool catalog	New tools added? Existing tool signatures changed?
Resource map	New resources? URI patterns changed?
Prompt list	New prompts? Prompt content contracts changed?
State model	New state properties? Property group changes?
Badge gating	New GM-only tools? Gating rules changed?
Behavioral contracts	Output format contracts changed? Error taxonomy changed?

Every gap gets a disposition: implemented (the fix was applied), deferred (intentional — recorded with rationale), or waived (REQ doesn't apply to this ruleset).

3. Implementation

The AI implements every gap marked implemented. Changes are applied incrementally — tool additions, signature updates, resource registration, prompt updates, state model extensions. Each change cites its REQ.

4. Scoped verification

The AI re-runs only the Pattern Buffer sub-workflows exercised by the changed surfaces — not the full suite. The surface-to-sub-workflow mapping in §6.6 determines which sub-workflows to run. S1 (tool surface sweep) is always selected when new tools are added.

Example: if only badge gating changed, only S6 (cross-badge boundary enforcement), S14h (Player badge manage_session (action: health)), and S20 are selected. Combat, search, and lore scenarios are skipped.

After verification, the server process is restarted and manage_session (action: health) confirms the updated specification version.

Source: spec §6.7, §6.6 (surface-to-scenario mapping).

What survives

Your campaigns survive every update. Characters, Novels, worlds — they don't notice the server changed underneath them.

Same ruleset rebuild: All Novel state preserved. Synthesis items with matching ruleset hash survive unchanged.
Spec-only update: Novel state preserved. The update is additive or corrective.
Ruleset changes: Novel state preserved, but synthesis is replaced when the ruleset hash changes and Synthesis re-runs.
Nuclear rebuild (deleting .holonovel-state/): Roster survives (it's in roster/). Novels must be re-imported from exports.

Source: spec §6.7 (Update and rebuild), spec §11 (Synthesis lifecycle).

After the update

Run manage_session (action: health) to confirm the server reports the new spec version. Check that your existing Novels resume without errors. If the update added new tools, verify they appear in your MCP client's tool list after restart.