The Founding Document

// internal/store/genesis.go
// Key is one line of the founding document: the key it is written
// under, the question it asks the operator, and whether the name it
// fixes is a thing you can have two of.
//
// Counts is not decoration. A program that has one form of a name and
// needs two makes the second one up, and a program that makes a plural
// up by adding a letter is a program that one day prints Firstlights.
// A name a world is going to print in both forms is written down in
// both forms, by the person who chose it.
type Key struct {
	Name   string
	Asks   string
	Counts bool
}

// Keys is the founding document's schema and its order.
//
// It lives here and not in the file, which is the whole of what makes
// this a document and not a bag of settings. A JSON object has no
// order; this list has one, and it is the order the lines go into the
// chronicle in. A key in the file that is not on this list is refused,
// and so is a key on this list that the file has not answered: an
// operator who skipped one did not decide to leave it out, they got
// as far as ten and were called away.
var Keys = []Key{
	{"world", "what the whole of it is called", false},
	{"ground", "the land it runs on", false},
	{"living", "what walks about on the ground", true},
	{"keeper", "who watches it", false},
	{"people", "where people gather", false},
	{"arrival", "how somebody gets in", false},
	{"way", "the doors from one piece of ground to the next", true},
	{"trade", "what changes hands", false},
	{"edge", "what is past the mapped ground", false},
	{"waste", "where what is finished with goes", false},
	{"sought", "the thing worth going after", false},
}

Eleven, and the count is a decision somebody has to make once. Fewer and the document stops being a founding and becomes a configuration file with a valley name in it. Many more and it stops being something an operator sits down and writes in an evening, which is the only kind of document that gets written honestly. The test for a key is whether a person who has never seen this world would need it to say one sentence about the place, and every one of the eleven passes that test today.

Counts is the field on that list most likely to be deleted by somebody tidying up, so here is what it does. Two of the eleven names get printed in both forms: the animals, and the doors. English makes plurals with a letter about ninety percent of the time, which is exactly the hit rate that gets a rule like that written into a program and then never revisited. The tenth case is the one on the front page. A name is a thing somebody chose, and the person who chose it is the person who knows what two of them are called, so the file asks and the loader refuses a countable name that came with one form.

{
  "opened": 0,
  "entries": {
    "world": {
      "one": "The World",
      "note": "This is The World. I built it and I run it, and on the tick this is dated to there is nothing in it but ground. I am writing the names down now, before anything happens that could disagree with them. I read this file once and then I leave it alone. Anything I want to say afterwards goes in the chronicle with a tick on it."
    },
    "ground": {
      "one": "The Hollow",
      "note": "The land is The Hollow. It is one valley with stone round the rim and soil in the bottom, and everything alive here is alive in it. It is the ground I have made, and not all the ground there is."
    },
    "living": {
      "one": "hobb",
      "many": "hobbs",
      "note": "The animals are hobbs. One of them is a hobb. They eat, walk, breed and die, and not one of them is named: they are numbered, and the numbers are in the archive."
    },
    "keeper": {
      "one": "Asteria",
      "note": "Asteria keeps it. She is not down in the valley and she does not walk about in it; she reads what the world writes down. That is the whole of what I have settled about her, and it is enough to be going on with."
    },
    "people": {
      "one": "Firstlight",
      "note": "People gather at Firstlight. Nobody is there and nothing stands there. The name is here at tick zero because this is the last moment a name can be put down and count as founding."
    },
    "arrival": {
      "one": "The Commons",
      "note": "The way in is The Commons. Anybody who comes here comes through it, and there is no second door."
    },
    "way": {
      "one": "Waygate",
      "many": "Waygates",
      "note": "The doors between one part of the ground and another are Waygates. One of them is a Waygate."
    },
    "trade": {
      "one": "grain",
      "note": "What changes hands is grain. Nothing here trades and nothing here is priced. I am writing the word down anyway, because it costs me one line today and cannot be had at all tomorrow."
    },
    "edge": {
      "one": "the Unwritten Places",
      "note": "Past the mapped ground are the Unwritten Places. It is the word for everywhere I have not built."
    },
    "waste": {
      "one": "the Midden",
      "note": "What is finished with goes to the Midden. Bodies, husks, whatever falls: it ends in one place and the ground takes it back."
    },
    "sought": {
      "one": "the Wellspring",
      "note": "The thing worth going after is the Wellspring. I know what it is called. I have settled nothing else about it and I am not going to today."
    }
  }
}

Read one of those notes and then read it again asking what kind of writing it is, because that question is the hardest part of this whole chapter and the part a reader is most likely to get wrong on their own file. It is a note. Somebody has built a thing, they are about to leave it running, and they are putting down what they made while they still remember making it. Present tense, plain sentences, first person, and the flat willingness to write I have settled nothing else about it where there is nothing else settled.

Three other registers are sitting right there and every one of them will produce something that reads better and works worse. There is the scriptural one, where the ground is spoken of as having been given rather than made. There is the mythic one, with an age before the valley and a reason the animals came. And there is the design document, with its bullet points about what the mechanism is for. All three describe a world from outside it. The note describes a world from the desk of the person who built it, which is the only vantage point that is actually true on the tick this file is dated to, and the only one that stays true when somebody reads it back in year forty and finds it has not aged into a promise.

It is easier to see on one key than in the abstract, so here is the edge of the map written three ways. The mythic one: Beyond the mapped ground lie the Unwritten Places, where no foot has fallen and no name has yet been given, and they wait. The design one: edge: the label for regions outside the generated grid; printed wherever a position falls off the valley. And the one in the file: Past the mapped ground are the Unwritten Places. It is the word for everywhere I have not built.

The first knows things the operator does not know. Nobody has established that no foot has fallen anywhere, and they wait is a promise dressed as a description; a reader who takes it seriously has been told something about this world that is not true of it. The second is true of the program on the afternoon it was written and stops being true the first time the program changes, which makes it the one register that actively rots. The third says who wrote it, says what the word means, and says the limit of what has been decided. It is the only one of the three that will still be accurate in year four hundred, because it is a statement about a decision and not about a world or about a code path.

The eight keys no code has any use for yet are the argument this whole page rests on, so the page is blunt about them. Three of the eleven names go on a line this world already prints: what the world is called, what the ground is called, what the animals are called. The other eight name things this valley does not have. There is no settlement in it, nothing arrives, nothing trades, nothing is sought, and the only place anything is finished with is a pile of litter with a number on it. Every one of those eight is written anyway, at tick zero, in one sitting, by somebody who does not know which of them is going to matter.

$ go run ./cmd/genesis -mode draft
genesis: a founding document, before there is anything to found

  genesis.json, and the eleven questions it answers

   key      asks for                                         the name it fixes      words  printed
   world    what the whole of it is called                   The World                 67  yes
   ground   the land it runs on                              The Hollow                41  yes
   living   what walks about on the ground                   hobb / hobbs              33  yes
   keeper   who watches it                                   Asteria                   45  no
   people   where people gather                              Firstlight                34  no
   arrival  how somebody gets in                             The Commons               19  no
   way      the doors from one piece of ground to the next   Waygate / Waygates        18  no
   trade    what changes hands                               grain                     34  no
   edge     what is past the mapped ground                   the Unwritten Places      18  no
   waste    where what is finished with goes                 the Midden                23  no
   sought   the thing worth going after                      the Wellspring            28  no
                                                                                      360

  11 keys, 360 words of the operator's own note, 2279 bytes of jsonb
  3 of the names go on a line this world already prints; the other 8 it has no use for
  dated to tick 0, which is the only tick a founding document is ever dated to

  and the four ways a document is refused
    a question left unanswered
      the founding document has no "sought": the thing worth going after
    an answer nobody asked for
      the founding document answers weather, which this world does not ask
    a countable name written once
      "living" names one hobb and no more: a name this world counts is written twice
    a plural on a name nothing counts
      "ground" names "The Hollow" and "The Hollows", and this world never counts them

No database anywhere near that run. The document is a file and the checks are arithmetic over it, so the first thing anybody does with a draft is the thing that needs nothing running. Three hundred and sixty words is the size to aim at. Under three hundred and the notes stop being notes and become labels; over five hundred and you are writing the myth.

The four refusals at the bottom are the loader run against a spoiled copy of the document, one thing wrong at a time. The two in the middle are a matched pair and the reason for both is the same. A missing answer is refused because a world founded on a blank prints a blank for the rest of its life, and the day somebody notices is a day far too late to fix it. An extra answer is refused because a key nothing asks for is a name nothing will ever read, and a file that accepts those silently is a file that accumulates them: three years on it holds a dozen words no row can account for, and no way to tell which of them the world is actually using.

DisallowUnknownFields on the decoder does half of that for free, at the level of the document's own shape, and the loop over Keys does the other half at the level of its contents. Both matter. The first catches a misspelt entries; the second catches a misspelt ground.

$ go test ./internal/store/ -run 'EveryQuestionTheDocumentAsksIsAnswered|AQuestionLeftUnansweredIsRefused|AnAnswerToAQuestionNobodyAskedIsRefused|ANameThisWorldCountsIsWrittenDownTwice|APluralNobodyAskedForIsRefused|TheLinesComeOutInTheDocumentsOwnOrder|TheDocumentComesBackOutOfTheBlobUnchanged' -v
=== RUN   TestEveryQuestionTheDocumentAsksIsAnswered
    genesis_test.go:55: 11 keys, 360 words of the operator's own note, and a name on every one of them
--- PASS: TestEveryQuestionTheDocumentAsksIsAnswered (0.00s)
=== RUN   TestAQuestionLeftUnansweredIsRefused
    genesis_test.go:65: store: the founding document has no "sought": the thing worth going after
--- PASS: TestAQuestionLeftUnansweredIsRefused (0.00s)
=== RUN   TestAnAnswerToAQuestionNobodyAskedIsRefused
    genesis_test.go:76: store: the founding document answers weather, which this world does not ask
--- PASS: TestAnAnswerToAQuestionNobodyAskedIsRefused (0.00s)
=== RUN   TestANameThisWorldCountsIsWrittenDownTwice
    genesis_test.go:88: store: "living" names one hobb and no more: a name this world counts is written twice
--- PASS: TestANameThisWorldCountsIsWrittenDownTwice (0.00s)
=== RUN   TestTheLinesComeOutInTheDocumentsOwnOrder
    genesis_test.go:106: 11 lines, all of them tick 0 and kind "genesis", in the order Keys names and no other
--- PASS: TestTheLinesComeOutInTheDocumentsOwnOrder (0.00s)
=== RUN   TestTheDocumentComesBackOutOfTheBlobUnchanged
    genesis_test.go:129: 2279 bytes of jsonb, and the same eleven answers back out of it
--- PASS: TestTheDocumentComesBackOutOfTheBlobUnchanged (0.00s)
=== RUN   TestAPluralNobodyAskedForIsRefused
    genesis_test.go:143: store: "ground" names "The Hollow" and "The Hollows", and this world never counts them
--- PASS: TestAPluralNobodyAskedForIsRefused (0.00s)
PASS
ok  	theworld/internal/store	0.006s

Seven tests on the document this build ships, and not one of them opens a socket. The fifth is the one that would be easy to leave out and is the reason the order lives in Keys: eleven lines come out in the order the list names, all of them at tick nought, and a Go map iterating in whatever order it feels like on the afternoon has no say in it. The sixth is the round trip. The document goes into the world row as two thousand two hundred and seventy-nine bytes of jsonb and comes back out as the same eleven answers, which is the only reason it is safe to stop reading the file.

// internal/store/genesis.go
// Genesis founds a world: the one world row, with the document in it,
// and the document's lines as the first rows the chronicle holds, all
// of it in one transaction.
//
// One transaction, for the same reason a snapshot is one. A world
// whose row exists and whose chronicle is empty is a world that was
// named by a file nobody can now read back, and a chronicle with
// founding lines in it and no world above them is a history of
// nothing. Neither state has to be reasoned about, because neither can
// be reached.
//
// The document goes into the world row whole, as one blob, and the
// same prose goes into the chronicle as rows. That is not two copies
// of one thing kept in step: the blob is the vocabulary, read back by
// name whenever the world prints one, and the rows are history, read
// back in order beside everything else that ever happened. They are
// written together and neither is ever written again.
func (d *DB) Genesis(ctx context.Context, doc Doc, seed uint64) error {
	world := doc.One("world")
	if world == "" {
		return fmt.Errorf("store: founding a world the document does not name")
	}
	blob, err := json.Marshal(doc)
	if err != nil {
		return fmt.Errorf("store: founding %q: %w", world, err)
	}
	tx, err := d.pool.Begin(ctx)
	if err != nil {
		return fmt.Errorf("store: founding %q: %w", world, err)
	}
	defer tx.Rollback(ctx)

	const row = `INSERT INTO world (world, seed, opened, genesis) VALUES ($1, $2, $3, $4)`
	if _, err := tx.Exec(ctx, row, world, int64(seed), doc.Opened, blob); err != nil {
		return fmt.Errorf("store: founding %q: %w", world, err)
	}
	const line = `INSERT INTO chronicle (tick, kind, text) VALUES ($1, $2, $3)`
	for _, l := range doc.Lines() {
		if _, err := tx.Exec(ctx, line, l.Tick, l.Kind, l.Text); err != nil {
			return fmt.Errorf("store: founding %q: the %q line: %w", world, l.Kind, err)
		}
	}
	if err := tx.Commit(ctx); err != nil {
		return fmt.Errorf("store: founding %q: %w", world, err)
	}
	return nil
}

Twelve statements, one transaction, one connection out of a pool of four. The pool is small on purpose and this is the sort of caller it was sized for: something that runs between ticks, holds a connection for as long as a founding takes, and hands it back. Nothing inside a tick is anywhere near it.

The tick this happens on is a boundary in the same sense the snapshot page used the word: nothing is part-way through, no view is open, no creature is half-stepped, because no creature has taken a step. Tick zero is the easiest boundary this world will ever have and the founding is taken on it for the same reason a save is taken on one. There is one moment at which the whole of a world can be written down without anybody having to say what was in flight, and a founding gets the cleanest instance of it going.

Not one of the eleven chronicle rows says which key it came from. The chronicle's columns are a tick, a kind and some text, and all eleven founding rows carry the same kind, because what happened was one thing: a world was named. How the file that carried the words was laid out is a fact about the file, and it is in the world row, in the blob, where the names are. That division is the one to hold on to, and the rest of this page is a demonstration of what it buys.

The database has to be empty for this, so start it empty. The data directory is a tmpfs, which means a restart is a fresh server with no rows anywhere in it, and the last thing the archive page did was leave the creature table loaded.

$ podman kill world-db && podman start world-db
world-db
world-db
$ podman exec -w /bench world-go go run ./cmd/genesis -mode found
genesis: a world named, on the tick before it has any history

  the document was read from genesis.json and will not be read again

  before it
    world      0 rows
    chronicle  0 rows

  one transaction: the world row and every line of the document
    world      1 row
    chronicle  11 rows

  the world row, read back
    world      The World
    seed       5
    opened     tick 0
    genesis    11 keys, 360 words

  the chronicle, ORDER BY entry, cut to fit
    entry  tick  kind      text
        1     0  genesis   This is The World. I built it and I run it, and on the tick...
        2     0  genesis   The land is The Hollow. It is one valley with stone round t...
        3     0  genesis   The animals are hobbs. One of them is a hobb. They eat, wal...
        4     0  genesis   Asteria keeps it. She is not down in the valley and she doe...
        5     0  genesis   People gather at Firstlight. Nobody is there and nothing st...
        6     0  genesis   The way in is The Commons. Anybody who comes here comes thr...
        7     0  genesis   The doors between one part of the ground and another are Wa...
        8     0  genesis   What changes hands is grain. Nothing here trades and nothin...
        9     0  genesis   Past the mapped ground are the Unwritten Places. It is the ...
       10     0  genesis   What is finished with goes to the Midden. Bodies, husks, wh...
       11     0  genesis   The thing worth going after is the Wellspring. I know what ...

  11 rows, all of them tick 0, in the order the document names its keys

Eleven rows numbered one to eleven, every one of them on tick nought. The numbers came from the database and could not have come from anywhere else: entry is GENERATED ALWAYS AS IDENTITY, so an insert that tries to supply its own is refused outright and there is no road by which a program puts a row in the middle of a history. The schema page argued for that column against exactly this case, because eleven things landing on one tick is a tick where the tick is not a key, and here are the eleven.

Notice what the founding did to the rest of the schema without doing anything to it. The snapshot table has a foreign key into world, so until this ran there was nowhere for a save to hang. The world row exists now and it is the last time it will be written.

// internal/store/genesis.go
// Doc reads the founding document back out of the world row. It is
// the only place a running world gets a name from once it has been
// founded, and it is asked once, when the process starts.
func (d *DB) Doc(ctx context.Context) (Doc, error) {
	var doc Doc
	// One row by construction: the world table takes one and the
	// database refuses a second. The ORDER BY is there because every
	// query in this book carries one and a rule with an exception is
	// a rule somebody has to remember.
	const q = `SELECT genesis FROM world ORDER BY world`
	var raw []byte
	if err := d.pool.QueryRow(ctx, q).Scan(&raw); err != nil {
		return doc, fmt.Errorf("store: reading the founding document: %w", err)
	}
	return ReadDoc(raw)
}

$ podman exec -w /bench world-go go run ./cmd/genesis -mode names
genesis: a world started with a document that has been edited since

  the file this process was handed, an edited copy of the founding document
    file                   genesis-79.json
    the ground             the Hollow

  what the database holds
    world                  The World
    ground                 The Hollow
    living                 hobb / hobbs
    keeper                 Asteria
    people                 Firstlight
    arrival                The Commons
    way                    Waygate / Waygates
    trade                  grain
    edge                   the Unwritten Places
    waste                  the Midden
    sought                 the Wellspring

  and the three of them this world puts on a line
    The World, on the ground it calls The Hollow, with hobbs walking about on it

  the file says "the Hollow" and the world says "The Hollow"
  the document was read on tick 0 and the names have come out of the database since

The file on disk says one thing and the world says another, and the world is right. There is no cleverness in that and no reconciliation step: the program never asks the file, so there is nothing to reconcile. ReadDoc is the same function in both cases, which is the small piece of design that makes it work at all. The bytes that come out of the column go through exactly the checks the file went through, so a world row somebody has been at by hand is refused on the way in rather than trusted because it came from a database.

// internal/store/genesis.go
// Tell appends one line to the chronicle. It is called between ticks
// and never inside one, like everything else in this package.
func (d *DB) Tell(ctx context.Context, tick int, kind, text string) error {
	const q = `INSERT INTO chronicle (tick, kind, text) VALUES ($1, $2, $3)`
	if _, err := d.pool.Exec(ctx, q, tick, kind, text); err != nil {
		return fmt.Errorf("store: telling the chronicle about tick %d: %w", tick, err)
	}
	return nil
}

// cmd/genesis, once a year, between one tick and the next
text := fmt.Sprintf("year %d: %d %s standing in %s, %d born and %d gone",
	y, live, held.Many("living"), held.One("ground"), born, deaths)
if err := db.Tell(ctx, w.tick(), "count", text); err != nil {
	die(err)
}

Two names go into that sentence and both of them came out of held, which is the document as the database handed it back when the process started. That is the whole mechanism of this chapter arriving where it matters. The plural is the one the operator wrote down rather than one the program derived, the ground is the one the world row holds, and the text that lands in the chronicle is a finished English sentence with the names already in it.

The database has to be empty again, because this run founds its own world. Ten years first, with nothing renamed in them, so that what a chronicle looks like when no file has interfered with it is on the page before the interference.

$ podman kill world-db && podman start world-db
world-db
world-db
$ podman exec -w /bench world-go go run ./cmd/genesis -mode years -years 10 -at 0
genesis: 10 years of one valley, and nothing renamed in it

  founded at tick 0: The World, on ground it calls The Hollow, 29 hobbs standing
  11 lines of the founding document in the chronicle, every one of them tick 0

   year     tick  walking     born     gone  chronicle
      1     3150       11       45       63         12
      2     6750       23       84       90         13
      3    10350       25      122      126         14
      4    13950       19      195      205         15
      5    17550       43      252      238         16
      6    21150       12      338      355         17
      7    24750       28      385      386         18
      8    28350      105      628      552         19
      9    31950      171      869      727         20
     10    35550      191     1013      851         21

  the chronicle at the end of 10 years
    rows                                            21
    of those, the founding document                 11
    and the yearly count                            10

  asking the history about the ground it has been running on
    the name the world row holds           The Hollow
      rows carrying it                              11
      first on tick                                  0
      last  on tick                              35550

  21 rows, one name, and every row that names the ground at all carries it

  35550 ticks in 10.286s, 3456 ticks a second (measured here; yours will differ)

The chronicle column is the one to watch and it is the least dramatic thing in the block: eleven rows before the first tick, then twelve, then thirteen, one a year, for ever. Everything else in that table is the valley behaving the way the pyramid chapter said it does. Twenty-nine animals go in, the population falls to eleven in the first year and to twelve again in the sixth, and then it climbs to a hundred and ninety-one by the tenth. Founders are scattered on a valley they did not grow up in, most of them starve, and the ones that do not are the ancestors of everything afterwards. The timing on the last line, and the one on the eighty-year run further down, are an eight-core Ryzen 7 3700X talking to itself and will be different on your machine; every other number in either block is arithmetic and comes out the same anywhere.

The last block is the one to hold in mind for the next two pages. Eleven rows of this history name the ground: the ten yearly counts, and the founding note about the ground itself. The first is on tick nought and the last on tick 35,550, which is the whole of the history, because a question asked by name in a world with one vocabulary gets the whole of the history. That is the property about to be lost.