@heroiclands/package-build 22.7.0 → 22.9.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @heroiclands/package-build
 
+## 22.9.0
+
+### Minor Changes
+
+**Calendars are content, not configuration.** The `calendar:` block retires from `package-build.config.yaml`, and a configuration that still declares it is refused by name.
+
+**A calendar is a note.** A `lore` note with `subType: calendar` states the months it keeps, the weekdays it names, the seasons it marks and the year-counts kept in it, and a date names one of those by writing `<calendar shortcode>.<era shortcode>`. Days that belong to no month are a short month like any other, sitting in the list where they fall in the year.
+
+**The world states its own year.** How long the year is, how the day divides and how the moon moves are written once on the world's own `place` note and on its moon's, so no calendar restates them — and a calendar whose months do not add up to that year is refused, naming the year rather than the arithmetic.
+
+**A body is a place.** `place` gains `celestial`, for something observed from a world rather than located on one.
+
+**A written day is bounded by the month it names.** A five-day month accepts five days and a thirty-day month accepts thirty, in whatever order a calendar keeps them; a package that names no calendar bounds nothing.
+
+## 22.8.0
+
+### Minor Changes
+
+**A being's dates**
+
+- A being says when it was born and when it died: `born:` takes over from `birthday:`, and `died:` sits beside it.
+- Either date may read `unknown` where it was never recorded; an absent `born` says the being was never born, and an absent `died` says it is alive.
+- `age:` is optional, and is an override — write it only where the number should win over the date, and write it `~34` where it is somebody's estimate.
+- A note still writing `birthday:` compiles identically and is told once what to write instead.
+- A profile reads its two dates ahead of the line describing the being's appearance.
+
+### Patch Changes
+
+**Dates**
+
+- A package can state how its year is divided — how many months, and how many
+  days to a month — and the date it treats as the present.
+- A refused `BF`/`AF` date now states the replacement rule instead of a computed value, which was wrong for `AF`.
+
+**The book**
+
+- A numbered or bulleted point whose text runs to more than one paragraph now
+  sets every paragraph flush under the point, so it reads as one block hanging
+  off its number instead of a stray indented paragraph beneath it.
+
+**A draft entry's notice**
+
+- The sentence sets in italic, with `Draft.` in bold ahead of it, on the page, in a journal entry and on an actor's dossier alike: the entry speaking about its own state rather than about the world.
+- In the book the notice's mark sits in a column of its own, so a sentence that runs to two lines sets both of them clear of it.
+- The mark is a filled disc with the exclamation knocked out of it, in the book's accent.
+- The sentence sets at the size, face and ink of the entry's prose; the rule down its edge and the mark are what set it apart.
+
 ## 22.7.0
 
 ### Minor Changes

package/docs/api.md

@@ -604,6 +604,51 @@ The closed registry of system ids, and the `none` that stands for no system at a
 | `assertSystemSegment`  | `assertSystemSegment(value, where)`    | `string` — the value, unchanged | refusing a value the `<system>` segment may not hold, validating inline                      |
 | `assertSystemCharset`  | `assertSystemCharset(segments, where)` | throws                          | refusing a registry declaration whose id could not be an address segment                     |
 
+### `engine.calendars`
+
+The axis every date normalises onto, the arithmetic over a calendar's month list, and the moon. A reckoning is an **era** declared on the note about the calendar that counts those years, and its epoch is the `start` written on that row — nothing is registered in configuration. The year conversion is piecewise on the sign, because the authored numbering has no year zero while the normalised value does: authored `-1` is `0`, and `-1` and `1` are adjacent. `lunarPhase` takes a floored modulo for the same reason the conversion branches: a truncated one is right on one side of an epoch and wrong on the other.
+
+| Export              | Signature                          | Returns                                | Use it when                                                                     |
+| ------------------- | ---------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------- |
+| `CANONICAL_EPOCH`   | `const CANONICAL_EPOCH`            | —                                      | naming where the canonical axis's own year 1 sits                               |
+| `canonicalYear`     | `canonicalYear(year, epoch?)`      | `number` — the signed year on the axis | converting a year written in one reckoning to the number everything compares on |
+| `dateSortKey`       | `dateSortKey(year, month, day)`    | `number`                               | ordering mixed-precision dates against a single number                          |
+| `calendarStructure` | `calendarStructure(calendar)`      | `{months}` — `null` where unstated     | reading the months a calendar keeps, before phrasing a finding                  |
+| `daysInMonth`       | `daysInMonth(calendar, month)`     | `number` — `null` where unstated       | bounding a written day against the month it names                               |
+| `daysInYear`        | `daysInYear(months)`               | `number`                               | asking what a month list claims the year is                                     |
+| `monthStarts`       | `monthStarts(months)`              | `number[]`                             | reading the same sum as a sequence, which is what an ordering error moves       |
+| `dayOfYear`         | `dayOfYear(months, month, day)`    | `number`                               | placing a written month and day in the year                                     |
+| `lunarPhase`        | `lunarPhase(day, epochDay, cycle)` | `number` — `0` to `cycle - 1`          | asking how far into its cycle a moon is, on either side of the epoch            |
+
+### `engine.noteDates`
+
+A date on a note is one authored string — `[~][-]YYYY[/MM[/DD]] [<calendar shortcode>.<era shortcode>]` — and every field holding one parses through a single grammar into a single record. Print `text`, order on `sort`, do arithmetic on `canonicalYear`. A bare value sits on the canonical axis and carries `era: null`; one naming an era carries the qualifier and no `canonicalYear` or `sort` keys at all until the era is resolved against the corpus. The literal `unknown` parses to the same record with the year half empty, carrying a null `sort` and a null `canonicalYear`, so nothing can order it to one end of a list.
+
+| Export                  | Signature                       | Returns                                            | Use it when                                                   |
+| ----------------------- | ------------------------------- | -------------------------------------------------- | ------------------------------------------------------------- |
+| `UNKNOWN_DATE`          | `const UNKNOWN_DATE`            | —                                                  | naming the literal that says a date is not recorded           |
+| `NOTE_DATE_PATTERN`     | `const NOTE_DATE_PATTERN`       | —                                                  | matching the date grammar directly                            |
+| `ERA_QUALIFIER_PATTERN` | `const ERA_QUALIFIER_PATTERN`   | —                                                  | checking that a string is an era qualifier a date could carry |
+| `parseNoteDate`         | `parseNoteDate(value, options)` | `{date, findings}` — `date` is `null` when refused | reading a note's authored date, with every finding it earned  |
+
+### `engine.calendarNotes`
+
+A calendar is a `lore` note with `subType: calendar`, declaring the months it keeps, the weekdays it names, the seasons it marks and the eras it counts years in. How long the year is, how the day divides and how the moon moves are facts about the **world**, written on its `place` note and its moon's, and no calendar may restate them — which is why the months summing to the world's year is the only arithmetic a calendar note is held to. One definition is emitted per calendar, in array shape: Foundry core prunes the keys outside its schema, and Calendaria converts the arrays to its own keyed collections.
+
+| Export               | Signature                                             | Returns                                    | Use it when                                                                 |
+| -------------------- | ----------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------- |
+| `CALENDAR_SUBTYPE`   | `const CALENDAR_SUBTYPE`                              | —                                          | naming the `lore` subType whose notes are calendars                         |
+| `INVARIANT_SUBTYPES` | `const INVARIANT_SUBTYPES`                            | —                                          | naming the `place` subTypes a world fact may be written on                  |
+| `CALENDAR_FIELDS`    | `const CALENDAR_FIELDS`                               | —                                          | reading the closed list of what a calendar note may declare                 |
+| `INVARIANT_FIELDS`   | `const INVARIANT_FIELDS`                              | —                                          | reading the closed list of what a body may declare about itself             |
+| `checkCalendarNote`  | `checkCalendarNote(note, opts)`                       | `object[]` — findings                      | holding a `lore` note to the family and to the year the world keeps         |
+| `checkWorldFacts`    | `checkWorldFacts(note, opts)`                         | `object[]` — findings                      | holding a `place` note's world facts to one body, one year and one moon     |
+| `worldInvariants`    | `worldInvariants(index)`                              | `{year, present, moon, body, moonName, …}` | reading the year, the present and the moon a package's own notes state      |
+| `quarterDays`        | `quarterDays(daysPerYear)`                            | `number[]` — four days of the year         | asking which days the year turns on                                         |
+| `compileCalendar`    | `compileCalendar({note, invariants, contentPackage})` | `object` — the definition                  | building the one object both a core consumer and Calendaria read            |
+| `compileCalendars`   | `compileCalendars(index, opts)`                       | `{calendars, invariants}`                  | building every calendar a package declares, or none where it states no year |
+| `calendariaEnvelope` | `calendariaEnvelope(definition, opts)`                | `object` — the import envelope             | wrapping a definition for a hand import through Calendaria's settings       |
+
 ### `engine.contentAddress`
 
 Where a content note publishes on the web. One rule, in one place, because two builds need the same answer: the knowledgebase build renders the page, and the link manifest records the address other packages link to. Stating it twice is how a manifest comes to assert a URL that resolves at build time and 404s for the reader.

package/docs/configuration.md

@@ -48,7 +48,7 @@ around its own evaluation.
 
 ### Quick reference
 
-21 top-level keys. `rootDir` is not one of them — a data configuration never
+22 top-level keys. `rootDir` is not one of them — a data configuration never
 writes it — and is documented under [Derived values](#derived-values) instead,
 alongside `foundryPackage`, `homepage`, `author` and `itemBuilders`, whose
 data-configuration behaviour is also derivation rather than ordinary
@@ -290,7 +290,7 @@ Unlike the first three, authoring `itemBuilders` is not an error — it is
 
 ---
 
-## The 21 keys
+## The 22 keys
 
 ### `contentPackage`
 

package/docs/content-format.md

@@ -2301,8 +2301,9 @@ Generates a living (or undead, or spirit) being.
 | `affiliations`              | `WikiLink[]`                                   | Affilliations (e.g., arcane/divine traditions, polities, etc)                                    |
 | `gender`                    | `male \| female \| other`                      | Gender of the character                                                                          |
 | `species`                   | `WikiLink`                                     | Being's species (lore)                                                                           |
-| `age`                       | `number`                                       | Age of the character                                                                             |
-| `birthday`                  | `YYYY/MM/DD`                                   | Date of birth of the character                                                                   |
+| `born`                      | `YYYY/MM/DD \| unknown`                        | When the being was born; absent, it was never born                                               |
+| `died`                      | `YYYY/MM/DD \| unknown`                        | When the being died; absent, it is alive                                                         |
+| `age`                       | `34 \| ~34`                                    | Age in years, stated only to override what `born` says; `~` marks an estimate                    |
 | `height`                    | `number`                                       | Height in meters                                                                                 |
 | `weight`                    | `number`                                       | Weight in kilograms                                                                              |
 | `frame`                     | `scant \| light \| medium \| large \| massive` | Relative frame size                                                                              |
@@ -2312,6 +2313,31 @@ Generates a living (or undead, or spirit) being.
 | `appearance.complexion`     | `string`                                       | Complexion                                                                                       |
 | `appearance.extra_features` | `string[]`                                     | Extra features                                                                                   |
 
+#### When a being was born, when it died, and how old it is
+
+**Absence asserts a fact rather than recording a gap**, and that is what these
+three fields are built around.
+
+- **`born` absent** says the being was **never born** — a construct, a spirit,
+  an elemental, a thing that was made. **`born: unknown`** says it was born and
+  the date is unrecorded, which is the commonest shape in a tree.
+- **`died` absent** says the being is **alive**, which is the common case and so
+  takes the cheapest form. **`died: unknown`** says it is dead and the date is
+  unrecorded. Both spellings of `died` mean dead.
+- **`age` is optional and is an override.** Written, it wins over anything the
+  dates say. Unwritten beside a dated `born`, it is the age that follows from
+  the date. Unwritten beside `born: unknown` or an absent `born`, the age is
+  unknown.
+
+Most people in a setting do not know their own birth date, so an age beside
+`born: unknown` is an ordinary complete record and not a note working around the
+schema. Where the number is somebody's estimate rather than a fact, write it
+`~34` — the same `~` a date carries.
+
+`birthday:` is the retired spelling of `born:`. Both are read and `born` wins,
+so a note compiles identically either way; the old spelling is reported until
+every tree has moved.
+
 #### The lead image
 
 **A being's portrait is the first thing inside its `{#appearance}` section,
@@ -3191,8 +3217,65 @@ In-world information about people, places, or concepts.
   tournament is not a matter of time-reckoning at all — and from `culture`, which is a grouping
   of people rather than an occasion they attend.
 
-| `data` property | Values | Description |
-| --------------- | ------ | ----------- |
+| `data` property | Values                                                                  | Description                                                                       |
+| --------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `epoch`         | `date`                                                                  | Which in-world day the world's clock reads zero on                                |
+| `months`        | `{ name, abbreviation?, days }[]`                                       | The months this calendar keeps, in order — the list sums to the world's year      |
+| `weekdays`      | `{ name, abbreviation? }[]`                                             | The days of the week it names, in order; a calendar with no week writes none      |
+| `seasons`       | `{ name, abbreviation?, monthStart?, monthEnd?, dayStart?, dayEnd? }[]` | The seasons it marks, bounded by month or by day of year                          |
+| `eras`          | `{ shortcode, name, abbreviation?, proclaimedBy?, start, end? }[]`      | The year-counts kept in it, each addressed `<calendar shortcode>.<era shortcode>` |
+
+#### What a calendar note declares
+
+**Those five keys belong to `subType: calendar` and to no other genre of
+`lore`.** A note carrying one under any other subType is refused, and a calendar
+note that states no `months` and no `epoch` is refused too: a calendar divides
+the year and says where the count begins, and one that does neither is prose
+about time rather than a calendar.
+
+```yaml
+type: lore
+subType: calendar
+shortcode: commoncal
+name:
+  full: The Common Calendar
+data:
+  epoch: 720/1/1
+  months:
+    - { name: Floralis, abbreviation: Flor, days: 30 }
+    - { name: Lusenar, abbreviation: Luse, days: 31 }
+    # … ten more, summing to the world's year
+  seasons:
+    - { name: Spring, monthStart: 1, monthEnd: 3 }
+  eras:
+    - shortcode: founding
+      name: After the Founding
+      abbreviation: AF
+      proclaimedBy: vylarinmpr
+      start: 1
+```
+
+**Position in the list is position in the year.** Days that belong to no month
+are a short month like any other: a five-day festival is one entry, and where it
+sits in the list is where it falls in the year. There is no intercalary
+mechanism, because there is nothing for one to do.
+
+**How long the year is, how the day divides and how the moon moves are facts
+about the world, not about a calendar**, so no calendar note states any of them
+— they are written once on the world's own `place` note and on its moon's, and
+every calendar is compiled against them. The one arithmetic check follows from
+that: `months` must sum to `year.days`, and a list that does not describes a
+different world rather than a different calendar.
+
+**An era is a way of counting years within a calendar**, so its rows sit beside
+the months. Each states its own `shortcode`, unique within the note, and a date
+names one by writing it after the calendar's address — `3 commoncal.founding`.
+`proclaimedBy` is optional: a reckoning whose proclaiming body is unknown, or
+whose body has no note, says so by leaving it out.
+
+**A calendar with no week writes no `weekdays`.** An empty list and an absent
+one say the same thing, and nothing downstream shows a weekday for a calendar
+that names none.
 
 ### type: map
 
@@ -3344,16 +3427,72 @@ three maps, and none of those maps needs to know it is a keep.
 - site: A place significant by what was made or done there — ruins, monoliths, henges, works, battlefields.
 - structure: A single building or habitation — halls, keeps, temples, inns, towers.
 - feature: A place significant by its terrain — forests, rivers, falls, passes, fords.
+- celestial: A body observed from a world rather than located on one — a sun, a planet, a comet.
+
+| `data` property                   | Values                                              | Description                                                                  |
+| --------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `demonym`                         | `string`                                            | What a person from this place is called — a Vylarian                         |
+| `lore`                            | `WikiLink[]`                                        | Lore concerning this place — its peoples, its law, its calendar, its history |
+| `parents`                         | `WikiLink[]`                                        | Enclosing places within which this place is located                          |
+| `population`                      | `number`                                            | Approximate population (precision 2 significant digits)                      |
+| `market`                          | `number`                                            | Market class, 1 to 6 — what trade a settlement supports                      |
+| `borders`                         | `{ to, bearing }[]`                                 | Places sharing a frontier with this one, and where each lies from here       |
+| `routes`                          | `{ to, bearing, mode, days, terrain?, leagues? }[]` | Journeys from this place's centre to another place                           |
+| `world.equatorialCircumferenceKm` | `number`                                            | The distance round the body at its equator, in kilometres                    |
+| `world.surfaceGravityG`           | `number`                                            | Surface gravity, as a multiple of Earth's                                    |
+| `world.axialTiltDegrees`          | `number`                                            | The tilt of the axis, in degrees                                             |
+| `year.days`                       | `number`                                            | How many days the body's year holds                                          |
+| `year.hoursPerDay`                | `number`                                            | How many hours the day divides into                                          |
+| `year.minutesPerHour`             | `number`                                            | How many minutes the hour divides into                                       |
+| `year.secondsPerMinute`           | `number`                                            | How many seconds the minute divides into                                     |
+| `present`                         | `date`                                              | The day the setting stops and play begins                                    |
+| `body.diameterKm`                 | `number`                                            | The body's diameter, in kilometres                                           |
+| `body.orbitalRadiusKm`            | `number`                                            | How far it orbits from the body it circles, in kilometres                    |
+| `body.orbit`                      | `string`                                            | The orbit's shape — `circular` means the cycle never varies                  |
+| `body.inclined`                   | `boolean`                                           | Whether the orbit is inclined to the plane the world orbits in               |
+| `moon.cycle`                      | `number`                                            | How many days it takes to return to the same phase                           |
+| `moon.newOn`                      | `date`                                              | A day it was new, written in the reference calendar                          |
+| `moon.eclipses`                   | `string`                                            | `never`, `rare`, `occasional` or `frequent`                                  |
+
+#### What a body states about itself
+
+**The four groups above are the world's own facts, and they are legal on a
+`world` or a `celestial` note and nowhere else.** A region, a settlement, a
+site, a structure or a feature is somewhere _within_ a world and says nothing
+about the world's year.
+
+```yaml
+# the world — type: place, subType: world
+data:
+  world: { equatorialCircumferenceKm: 40000, surfaceGravityG: 1.0, axialTiltDegrees: 23.5 }
+  year: { days: 365, hoursPerDay: 24, minutesPerHour: 60, secondsPerMinute: 60 }
+  present: 720
+
+# its moon — a note of its own, because a moon is a body and not a property
+data:
+  body: { diameterKm: 3800, orbitalRadiusKm: 388600, orbit: circular, inclined: true }
+  moon: { cycle: 30, newOn: 720/1/1, eclipses: rare }
+```
 
-| `data` property | Values                                              | Description                                                                  |
-| --------------- | --------------------------------------------------- | ---------------------------------------------------------------------------- |
-| `demonym`       | `string`                                            | What a person from this place is called — a Vylarian                         |
-| `lore`          | `WikiLink[]`                                        | Lore concerning this place — its peoples, its law, its calendar, its history |
-| `parents`       | `WikiLink[]`                                        | Enclosing places within which this place is located                          |
-| `population`    | `number`                                            | Approximate population (precision 2 significant digits)                      |
-| `market`        | `number`                                            | Market class, 1 to 6 — what trade a settlement supports                      |
-| `borders`       | `{ to, bearing }[]`                                 | Places sharing a frontier with this one, and where each lies from here       |
-| `routes`        | `{ to, bearing, mode, days, terrain?, leagues? }[]` | Journeys from this place's centre to another place                           |
+**`year.days` is where the year's length lives, and every calendar in the
+package is compiled against it.** A package whose notes state no `year` has no
+calendar mechanism at all: no sum is checked, and nothing is emitted. That is
+the right answer for a package building a setting whose world facts somebody
+else wrote down.
+
+**One year and one moon to a package.** Two years is two settings and nothing
+can say which one a calendar divides; a `moon` with no `year` anywhere is
+refused, because a cycle counted in days has no year to be measured against.
+
+**`present` is the day an age is computed against**, written in the grammar a
+note's dates are written in, so a setting whose present is best said in an era
+says it that way.
+
+**`world.axialTiltDegrees`, the circumference, the gravity, the moon's diameter
+and its orbital radius are read by nobody.** They are there so a reader knows
+what kind of world this is. What the build consumes is the year, the day's
+divisions, the present, the moon's cycle and epoch, and whether its orbit is
+circular and inclined.
 
 #### What a settlement's market supports