last-hearth/docs/m0-decisions.md

M0 decisions and verification ledger

Updated: 2026-11-02. Historical M0 record: M0 completed against its verified Windows technical gates. M1 implementation and automated verification are now complete; human route/repeat/performance acceptance remains pending (see M1 evidence). This is the M0 working rules/engineering baseline, not user/operator sign-off of policy or deployment. See roadmap and launch acceptance checklist.

Version and platform contract

Decision	Baseline / qualification
Engine	Exact stock Luanti 5.18.0, checked by launcher version response. The broad minimum in game.conf does not widen this tested contract.
Game	0.5.0-m4 current development release candidate, independent game repository/package; engine stays separately installed. M0/M1/M2/M3 versions below are historical evidence snapshots.
Save	Schema 1 envelopes for needs, claims, homes, access, location and spawn; legacy validation/migration, not a promise to accept arbitrary future data.
Tooling	Node.js 22+, built-in modules; release/package/backup format 1. See release metadata.
Clients	Native-first; Windows integrated and GUI checks verified on the existing development host. Linux/macOS path selection unit-tested only; native execution unverified. No clean-machine certification.
Browser	Not promised launch-ready. Advertise only after an explicit scope decision and actual M1 input/network/graphics/performance proof.
Engine changes	Stock baseline first; only a bounded M1 spike justified by measured feel/API limitations. No fork assumed.

Rules retained through M0

Area	Current rule / next decision
Death	Preserve inventory; respawn resets needs to existing defaults (food 85, water 85, warmth 80, wet 0, stamina 100) and attempts arrival. This temporary free-refill behavior remains a known limitation until M2; no final fair-recovery approval.
Offline	Logged-out player needs do not decay. Fuel uses absolute real-time expiry (maximum stored reserve read as 600 seconds). No queued cooking, crops or food spoilage yet; no invented offline crop/food contract. M4 owns bounded process accounting.
Claims	One per owner; 25 × 25 inclusive footprint (±12 X/Z), ±24 Y; up to 16 shared residents/storekeepers, action-specific access and claim bounds shown on request. Placement centers must be at least 26 blocks apart on an X or Z axis. General indirect-fluid/fire grief and public multiplayer authorization remain limited.
Progression ceiling	Preserve improvised flint tools, small timber/thatch palette, hearth, cup and forage loop. Pottery/storage and one useful metal tier are planned M4 scope, not M0 features.
Calendar	Host real UTC, local solar time and meteorological season labels; disclosed sky/climate approximation. No civil timezone/DST support yet (M2). Rest does not skip the shared clock.
Location	Local choice stays local; dedicated server needs explicit valid admin settings. No geolocation request. User/operator must approve the community location before M2 climate staging. No location is chosen by this document.
Fixtures	Seed 731104; synthetic 45°N, 0°E for M0 checks and fixed summer/winter. This is not production configuration or community-location approval.

For deployment, administrators must explicitly set hearth_environment to staging or production and set hearth_latitude and hearth_longitude to approved values. Dedicated defaults to production; dedicated local is rejected. Production rejects nonempty hearth_preview_date, weather other than auto, and any presence of hearth_launcher_mode or hearth_smoke_token. Remove those test keys, rather than assuming a false/empty launcher flag is safe. Local managed play explicitly uses local. These guards are not a complete server deployment.

Provisional performance acceptance targets — not measurements

These are implementation decisions to test, not measured results, certified minimum hardware, or accepted launch budgets. They may be revised explicitly in M1 after evidence, with user/operator review of any scope impact.

Target	Provisional acceptance envelope
Native client	4-core CPU, 8 GB RAM, integrated GPU supporting OpenGL 3.3; 1920 × 1080, low settings, view range 96 nodes. Target 60 FPS and p95 frame time ≤25 ms.
Server	4 vCPU, 8 GB RAM, 10 concurrent real clients; p95 server step ≤50 ms in the declared course/load scenario.
Network	Test RTT 0 / 80 / 150 ms, jitter 20 ms, packet loss 1%; record actual achieved conditions and an unshaped reference.

FPS and p95 frame time are separate checks; neither is inferred from the other. Record CPU/GPU models, OS/driver, engine/game revision, settings, route duration, warmup, sample count, client count, shaping method/direction and actual latency. Report memory, corrections, media transfer and stalls as observations before inventing additional limits. No benchmark or 10-player result was produced by this M0 record. The M1 fixture plan defines the next controlled experiment.

Storage, migration and recovery decisions

• HEARTH_HOME selects the local runtime root. Keep the existing Windows root and world unchanged; use a different absolute override for staging and an explicit HEARTH_ENGINE if needed. Production data/configuration belong to a separately operated external deployment, not the repository or game package.
• Packaging is a new game directory with deterministic generated assets and exact SHA-256 inventory, not an installer or engine bundle. Package/backup/ restore refuse existing destinations and unsafe paths/links.
• All relevant local/external/remote engines must be stopped before snapshots or restore. --offline is mandatory for CLI backup/restore. Lock checks are conservative signals, not proof of remote idleness.
• An existing managed play world gets a full prelaunch snapshot. Legacy records also get immutable per-key backup bytes before schema migration. Per-key rollback is best-effort, not an engine metadata transaction or crash-durability guarantee. Full offline snapshots remain necessary.
• Backups contain private authentication/player/world data. The operator owns access control, encryption, capacity/retention and off-host copies. SHA-256 detects corruption, not authenticity. No automatic retention deletion exists.
• Restore to a new destination, verify and rehearse before an explicit cutover; never overwrite the sole old world. Recovery tooling boots copies only. See README procedures and persistence architecture.

Verification and acceptance ledger

M0 technical verification is complete within the Windows scope below. No user/operator approval is recorded. The final verification record contains current counts, package digests, environment, commands, bounded logs and the distinct earlier recovery report. Private logs/snapshots remain outside the repository; neither source paths nor source-world contents are published.

Gate	Owner	Current evidence / status
Extracted game loads all modules, exact release contract	Technical agent	Complete: Luanti 5.18.0, game 0.1.0-m0, schema 1; current check/smoke and GUI require the verified package-load marker.
Node tooling and integrated Lua/engine suites	Technical agent	Complete: 17 Node tests; 123 Lua checks in seven isolated suites; 24 Lua files compiled; check/smoke/test markers and zero exits.
Fresh package verifies and repeats; tampered/missing/extra content rejected	Technical agent	Complete: two new external exports, identical manifests, 57 payload files; tamper/missing/extra/empty-directory rejection covered by passing tooling tests. Stale default dist was not reused.
Original old save unchanged, immutable snapshot, two restores and copy-only restart/migration	Technical agent	Complete retained evidence: 160 assertions (79 seed + 81 restart), two byte-exact restores and two successful shutdowns. Earlier package digest explicitly retained; not a new final-package recovery run. Source had zero claims; fixture/mock protection checks are not preservation of source claims.
Clean package and GUI play on verified development setup	Technical agent	Complete Windows technical scope: fresh external export verifies; current play loads the identical manifest digest in disposable HEARTH_HOME, client joins/leaves, normal shutdown and embedded-copy cleanup. Not a new-machine/clean-checkout certification. Linux/macOS native unverified.
First-session, summer/winter, production rejection, invalid/future schema refusal	Technical agent	Complete: current tooling fixture/production test and integrated schema, persistence, clock, runtime and player suites.
Play continuity and staging isolation; storage custody	Technical agent; user/operator for storage	Current isolated GUI pass; earlier launcher-agent two-launch regression verified metadata/sentinel continuity, two snapshots and cleanup. Original world not opened. Private ACL/encryption/retention and production authorization remain operator duties, not claimed certifications.
Rules, provisional scope, community location and acceptance	User/operator; technical agent for record	Rules, provisional review targets and risk owners recorded, completing M0 technical decision capture. No user approval fabricated. M1 human review and community-location approval before shared climate staging remain outstanding.

M0 technical work is complete; the initial M1 implementation and automated verification are complete, but its human acceptance gate remains open. This does not accept the full launch checklist F17–F19, authorize production, certify a new machine or expand native support beyond the observed Windows run. Final product and deployment acceptance stays with the user/operator. Provisional budgets and later location approval retain their explicit milestone owners.

Risk register and ownership

“Technical agent” owns implementation/investigation and evidence, not permission to approve deployment. “User/operator” owns policy, infrastructure and acceptance.

Risk / known limit	Owner	Milestone / mitigation
Integration differs from isolated tests; regression counts become stale	Technical agent	M0 checks complete and digests recorded; rerun regression suites for each M1 code change.
Legacy migration/crash loses state; metadata writes lack transactions	Technical agent; user/operator for backup custody	M0 evidence and M5 recovery rehearsal; preserve original, verify copy-only restore, never claim atomic durable migration.
Shared-world writer defeats offline assumptions; private backup leakage/storage exhaustion	User/operator; technical agent for tooling safeguards	M0 onward: stop all engines, protected/encrypted external storage, capacity/retention review.
Linux/native or macOS portability/clean-machine assumptions	Technical agent	M0/M1: real host evidence before expanding supported-client claims.
Sprint oscillation, collision/camera problems; stationary combat not compelling	Technical agent	M1: course, feedback and bounded stock-versus-custom decision. Not fixed by module extraction.
Unsafe saved arrival, failed emergence or death refill	Technical agent	M2 technical implementation and eight fixed-seed engine verification complete; blanket Y=-100 teleport is replaced by map-bound safe recovery, ±64-node fallback, owned-claim homes and partial needs recovery. Unfamiliar-tester acceptance remains open; see M2 evidence.
Wrong community location, seasonal imbalance, timezone or sky misunderstandings	User/operator for location; technical agent for model/validation	Approval before M2 climate staging; synthetic fixtures never imply production selection.
Bounded room/support model and shared roles remain prototype-level	Technical agent; user/operator for acceptance	M3 implementation and automated verification complete; two-player cabin, comfort and grief-resistance acceptance remains open. See M3 evidence.
Resource depletion and incomplete offline processes	Technical agent	M4: renewal/preservation before consequential spoilage and bounded idempotent accounting.
Public auth/moderation/deployment not hardened	User/operator for access policy/operations; technical agent for implementation	M5/M6: security/recovery review and real closed alpha before announcement.
Provisional budgets fail or browser scope expands silently	Technical agent for measurements; user/operator for scope	M1: report actual hardware/network evidence; revise targets explicitly, no invented measurements.