Errors That Don't Lie

// internal/sim/terrain.go — the imports grow, and one sentinel appears
import (
	"errors"
	"fmt"
	"strings"
)

// ErrOutOfBounds reports a coordinate that names no cell on this grid.
var ErrOutOfBounds = errors.New("coordinate is off the grid")

// At returns the terrain at a coordinate, or an error if the
// coordinate names no cell.
func (g *Grid) At(c Coord) (Terrain, error) {
	if !g.In(c) {
		return Rock, fmt.Errorf("terrain at %v: %w", c, ErrOutOfBounds)
	}
	return g.cells[g.index(c)], nil
}

// Set overwrites the terrain at a coordinate, or refuses if the
// coordinate names no cell.
func (g *Grid) Set(c Coord, t Terrain) error {
	if !g.In(c) {
		return fmt.Errorf("set terrain at %v: %w", c, ErrOutOfBounds)
	}
	g.cells[g.index(c)] = t
	return nil
}

// cmd/worldd/main.go — poke the new contract
	t, err := g.At(sim.Coord{X: 5, Y: 3})
	fmt.Println("at {5 3}:", t, err)
	t, err = g.At(sim.Coord{X: -1, Y: 5})
	fmt.Println("at {-1 5}:", t, err)
	err = g.Set(sim.Coord{X: 12, Y: 0}, sim.Soil)
	fmt.Println("set {12 0}:", err)

$ go run ./cmd/worldd
at {5 3}: water <nil>
at {-1 5}: rock terrain at {-1 5}: coordinate is off the grid
set {12 0}: set terrain at {12 0}: coordinate is off the grid

Read the signature first: At now returns two values, and Go makes the caller catch both. That is the idiom's teeth.

You cannot take the terrain and ignore the fact that there might not be any. The compiler rejects a call that binds one result of a two-result function.

The second poke shows a refusal: {-1 5}, the exact coordinate the scout corrupted itself with, now comes back with an error naming the operation, the coordinate, and the objection.

It also comes back with rock, and that first result is filler. When err is non-nil, the other return exists only because the signature demands something, and a caller that touches it before checking err has already lost. Error first, result second, every time.

Two details carry weight. ErrOutOfBounds is a package-level variable, a sentinel: one shared error value that means this one condition, exported so callers can recognize it later.

The %w verb in fmt.Errorf wraps the sentinel inside the longer message instead of pasting its text. The returned error carries the readable sentence on the outside and the identity of ErrOutOfBounds intact on the inside. Stage 3 collects that debt.

One consequence stays inside the package. Render called the old At in its loop, and its coordinates are generated by the loop itself, provably on the grid. It now reads g.cells[g.index(...)] directly.

Generate is the same case. Its soil loops run between the rim's bounds and its water walk refuses any step that would leave the interior, so every coordinate it writes is one it just proved, and it too assigns through g.cells[g.index(...)].

The boundary checks. Interior code that manufactures its own valid coordinates does not pay the toll twice.

// internal/sim/entity.go — sentinels and the one placement rule
var (
	// ErrNoEntity reports an ID the world has no entity for.
	ErrNoEntity = errors.New("no entity with that ID")
	// ErrBlocked reports terrain that refuses to hold an entity.
	ErrBlocked = errors.New("terrain refuses the entity")
)

// allows reports whether kind k may stand at a coordinate:
// nil for yes, an error naming the objection for no.
func (w *World) allows(k EntityKind, at Coord) error {
	t, err := w.Ground.At(at)
	if err != nil {
		return err
	}
	if k == Walker && t == Water {
		return fmt.Errorf("%v at %v is %v: %w", k, at, t, ErrBlocked)
	}
	return nil
}

// Spawn places a new entity and returns its ID, or refuses.
func (w *World) Spawn(k EntityKind, at Coord) (EntityID, error) {
	if err := w.allows(k, at); err != nil {
		return 0, fmt.Errorf("spawn: %w", err)
	}
	id := w.nextID
	w.nextID++
	w.ents[id] = &Entity{ID: id, At: at, Kind: k}
	return id, nil
}

// Get returns the entity with the given ID, or refuses.
func (w *World) Get(id EntityID) (*Entity, error) {
	e, ok := w.ents[id]
	if !ok {
		return nil, fmt.Errorf("entity %d: %w", id, ErrNoEntity)
	}
	return e, nil
}

// Move steps an entity to a new coordinate, or refuses and
// leaves the entity where it was.
func (w *World) Move(id EntityID, to Coord) error {
	e, ok := w.ents[id]
	if !ok {
		return fmt.Errorf("move entity %d: %w", id, ErrNoEntity)
	}
	if err := w.allows(e.Kind, to); err != nil {
		return fmt.Errorf("move entity %d: %w", id, err)
	}
	e.At = to
	return nil
}

// cmd/worldd/main.go — three requests, two of them doomed
	w := sim.NewWorld(g)

	scout, err := w.Spawn(sim.Walker, sim.Coord{X: 2, Y: 5})
	fmt.Println("spawned walker:", scout, err)

	drowned, err := w.Spawn(sim.Walker, sim.Coord{X: 5, Y: 3})
	fmt.Println("spawned walker:", drowned, err)

	_, err = w.Get(99)
	fmt.Println("lookup 99:", err)

$ go run ./cmd/worldd
spawned walker: 1 <nil>
spawned walker: 0 spawn: walker at {5 3} is water: terrain refuses the entity
lookup 99: entity 99: no entity with that ID

Follow one refusal end to end, because the layering is the lesson. Spawn asks allows; allows asks the grid, gets water back cleanly, applies its own rule, and returns ErrBlocked wrapped in a sentence naming the kind, the coordinate, and the ground.

Spawn wraps that once more with the operation that failed. Each layer adds the context only it knows, and the final message reads as a complete diagnosis a log file can stand on its own.

The comma-ok form e, ok := w.ents[id] distinguishes "absent" from "present". The absent case becomes a real answer with the missing ID in it, not a nil pointer waiting to detonate in whoever asked.

Every mutating path now refuses before touching state; a declined Move leaves the walker exactly where it was.

// cmd/worldd/main.go — the failure's march, against the hardened API
	w := sim.NewWorld(g)
	scout, err := w.Spawn(sim.Walker, sim.Coord{X: 2, Y: 5})
	must(err)

	at := sim.Coord{X: 2, Y: 5}
	for {
		next := at.Offset(-1, 0)
		if err := w.Move(scout, next); err != nil {
			fmt.Println("stopped:", err)
			fmt.Println("off the grid?", errors.Is(err, sim.ErrOutOfBounds))
			fmt.Println("blocked by terrain?", errors.Is(err, sim.ErrBlocked))
			break
		}
		at = next
		fmt.Println("walker", scout, "at", at)
	}

	e, err := w.Get(scout)
	must(err)
	fmt.Println("the world is still running; the walker stands at", e.At)

$ go run ./cmd/worldd
walker 1 at {1 5}
walker 1 at {0 5}
stopped: move entity 1: terrain at {-1 5}: coordinate is off the grid
off the grid? true
blocked by terrain? false
the world is still running; the walker stands at {0 5}

Set this run beside the worked failure, same walker, same westward march. Before: six moves deep into negative coordinates, halted by phantom water, state corrupted, and a sibling walker's identical mistake killing the process.

After: two legal steps, one refusal at the exact edge, and a walker standing at {0 5} in a world still running.

errors.Is answers true for ErrOutOfBounds through two layers of wrapping, because %w preserved the chain: the move wrapper, the terrain message, the sentinel at the core.

A plain == against the sentinel would answer false here, since the outermost error is the wrapper, not the sentinel itself.

That is the pattern this book needs: sentinels for the conditions callers decide on, %w to add context without destroying identity, errors.Is to ask. Deeper machinery can wait until the world has a use for it.

The must(err) helper deserves its two lines, because it looks like a cheat and is a policy. main builds its valley from loop counters that cannot leave the grid, so if Set refuses one of them, the request was not bad; the program is.

must panics on any error it is handed. A returned error and a panic answer different questions: the error says "this request cannot be honored", the panic says "this code does not do what its author believed".

The first is Tuesday for a server. The second should be loud, immediate, and fatal, and now it is chosen instead of ambient.