# URL policy

A ten-year reference work's most valuable asset is its unchanged URLs, and the only thing that
protects them is a written rule that outlives whoever is editing. This is that rule. Read it with
`EDITORIAL-GUIDELINE.md`.

## The governing principle

**An identifier is an accession number that happens to be readable. It is not a description.**

Every ID on this site encodes facts that could turn out to be wrong — `kptbb-english-6-en` asserts a
board, a subject, a class and a medium. When one of those is corrected, **the correction goes in the
record's fields and the ID stays as it is.** A URL that changes when a typo is fixed is not an
identifier; it is a description pretending to be one.

The cost of this rule is occasional IDs that mildly misdescribe their record. That cost is paid
willingly. The alternative is breaking every citation anyone has ever made.

## The schemes

| Pattern | Example | Rule |
|---|---|---|
| `/books/{id}/` | `/books/kptbb-english-6-en/` | `{board}-{subject}-{class}-{medium}`. Frozen at creation. Never regenerated from metadata. |
| `/books/{id}.json` | `/books/kptbb-english-6-en.json` | Machine record for the same ID. |
| `/findings/{slug}/` | `/findings/openness-is-allocated-not-absent/` | Content slug, frozen at creation. **Never derived from array position, sort order, or category.** |
| `/studies/{name}/` | `/studies/synthesis/` | Source filename in `analysis/`, lowercased. |
| `/axes/{slug}/` | `/axes/religious-saturation/` | Axis name, not its `A{n}` code — the codes are an internal ordering and could be renumbered. |
| `/boards/{code}/` | `/boards/kptbb/` | Board code, lowercased. |
| `/compare/{cell}/` | | Cell key, frozen at creation. |

### Findings IDs, specifically

Findings will grow from tens to hundreds, and the failure modes are known:

- **Never derive an ID from position.** A re-derivation would renumber every finding and break every
  citation at once. Current IDs are content slugs, which are immune to this.
- **Never embed the category.** A finding reassigned from `Gender` to `Method` must keep its URL.
  Category lives in the metadata, not the identifier.
- **Freeze the slug at creation.** A finding's *title* may be reworded — one already has been, after
  a correction — and the slug must not follow it. The slug records what the finding was called when
  it was created, and that is all it needs to do.

## Known weaknesses, recorded rather than hidden

1. **Study heading anchors are autogenerated from heading text** (`#2-the-scored-table`), so
   rewording a heading changes the anchor and breaks any deep link to it. Hand-authored mnemonic
   anchors would be more durable. The cost is hand-editing every heading across nineteen documents;
   the decision is to accept the risk and **treat heading rewording as a breaking change** — if a
   heading must be reworded, keep the old anchor as an empty span at the same position.
2. **Internal links are absolute** (`/books/…`), not relative. This forecloses the cheap version of
   frozen editions (see below) — an archived page's cross-references would resolve to today's
   version rather than to its own edition's siblings. Retrofitting is expensive and grows more so.
   If frozen editions are ever wanted, this is the change to make first.
3. **`/studies/{name}/` follows the source filename**, so renaming a file in `analysis/` moves a
   published URL. Renames there are breaking changes and need a redirect.

## Rules for change

- **Never change a URL.** Add a redirect instead. If the site is ever hosted somewhere that supports
  them, maintain a redirect map in the repository; if not, keep the old path as a stub page that
  points at the new one.
- **Adding is free, moving is not.** New sections, new facets and new record types cost nothing.
  Reorganising existing ones costs every inbound link and every citation.
- **The Astro configuration is deliberate**: `trailingSlash: 'always'`, `format: 'directory'`,
  per-page canonical URLs, and a sitemap. Changing any of those silently changes every URL on the
  site. Do not.
- **Corpus versioning belongs in the page, not the path.** The footer prints a record count and a
  date; citations reference that. Putting a version in the URL would fork the site.

## If frozen editions are ever built

The durable form for a project whose findings will be disputed and revised is a quarterly frozen
edition at `/archives/{edition}/…`, with the live site always at the bare path. The prerequisite is
weakness 2 above: **internal links must be relative, or resolvable under a version prefix, before
the first edition is frozen.** A frozen edition whose cross-references escape into the live site is
not an edition; it is a broken copy.

## If the project stops

The URLs stay alive and the pages stay as they are, with a dated banner saying the work stopped and
when. A stale reference that says it is stale remains useful. A dead link destroys every citation
made to it. This is stated publicly in `/standards/`, and it is a commitment, not an aspiration.