{
  "contract": "course-content/1",
  "slug": "ritual-the-state-ladder",
  "title": "The State Ladder: Observed, Witnessed, Consecrated",
  "primitive": "ritual/1 transitions",
  "audience": "Anyone integrating ritual/1 or designing a similar witnessed-practice API",
  "summary": "How ritual/1's four transitions — observe, witness, consecrate, project — each return a new, fully-revalidated fragment, and why editing or deleting an observance has no API at all: a correction is a new observance that supersedes, never a rewrite.",
  "track": "ritual-the-present-tense-track",
  "pin": {
    "source": "@flashyos/ritual — the transition kit: every call re-validates the whole fragment; a correction is a new observance, never a rewrite",
    "ref": "flashyos:packages/ritual",
    "revision": "dfa8c88e71077d70535e1ded0cfd85e032fa40d2",
    "state": "current"
  },
  "intro": [
    "ritual/1 is not just a document shape — it ships as a small library with a deliberately narrow set of verbs. This track is the practical side: what each transition does, what it refuses, and why the refusals are as load-bearing as the transitions themselves.",
    "Two lessons. ritual/1: the Present Tense first if you have not taken it — the doctrine explains why these mechanics are shaped the way they are."
  ],
  "lessons": [
    {
      "n": "01",
      "title": "Four verbs, and every one re-validates the whole fragment",
      "outcome": "Name the four transitions and explain why each returns a new object rather than mutating in place.",
      "body": [
        "The library exposes exactly four transitions: `observe` records that a liturgy was performed, `witness` attaches a corroborating attestation, `consecrate` turns a witnessed observance into one that carries consequence, and `project` reads the fragment's current state — including the honest one-line summary of how much of what was observed actually carries consequence.",
        "Every transition returns a NEW fragment and re-validates the entire thing — not just the piece that changed. A rule broken anywhere throws with every problem listed, not the first one found, which matters in practice: an integration that fixes one violation and re-runs learns about the next one immediately rather than in a second round-trip.",
        "This shape also makes the library safe to build a UI or a CLI on top of: nothing you call can leave the fragment in a state the validator itself would reject, because the validator runs on every single call, not just at the boundary where a fragment is first accepted."
      ],
      "source": {
        "label": "@flashyos/ritual — the transition kit",
        "href": "https://flashyos.com/packages/ritual"
      }
    },
    {
      "n": "02",
      "title": "There is no edit and no delete — a correction is a new observance",
      "outcome": "Explain why the library has no API for editing or deleting a recorded observance.",
      "body": [
        "Editing or deleting an observance has no API at all — not a permission you can lack, a function that does not exist. If a recorded observance turns out to have been wrong, the fix is a NEW observance that supersedes the old one, not a rewrite of the original.",
        "This is the same append-only discipline the estate holds for `shipped/1` and for corrections generally: a correction is appended, never edited. A log you can quietly edit is a log where 'the record now agrees with what actually happened' and 'the record now agrees with what somebody wishes had happened' are indistinguishable from the outside — and only the append-only version lets a stranger tell them apart by reading the history.",
        "`consecrate()` inherits two hard refusals from this same discipline: it throws on anything but a `person/` identity, and it throws on an unwitnessed observance. Both are structural, not advisory — there is no flag to consecrate 'anyway', because a flag like that is exactly the shortcut the whole ladder exists to close off."
      ]
    },
    {
      "n": "03",
      "title": "Three doors in, and a CLI that refuses no less than the library does",
      "outcome": "Name the three ways to integrate ritual/1, and explain why the CLI cannot save an invalid fragment the library would reject.",
      "body": [
        "ritual/1 offers three doors, and an adopter picks one rather than all three: copy the vendored file with no toolchain and no install (`node vendor-ritual.mjs check ritual.fragment.json`), import the npm package — whose entry IS the vendored file, so both doors run identical code — or validate independently against the published JSON Schema, checked against the conformance corpus for the cross-field rules a schema alone cannot express.",
        "The join kit — `init`, `liturgy`, `observe`, `witness`, `consecrate`, `check` — is the vendored file itself, runnable with bare node and no install. Every WRITING command runs the full validator before it saves, so the CLI can refuse nothing less strictly than the library does; there is no fast path that skips validation because a human typed the command instead of calling the function.",
        "`check <https://your-domain.example>` is worth calling out on its own: it fetches `/.well-known/ritual.json` over the network the way a stranger actually would, because a fragment that is green in your checkout and 404 at your own domain reads as success everywhere except where a real reader stands. A failed fetch is reported as this machine's own view, never as a fact about the domain — a proxy refusal and a genuinely down host look identical from here, and the tool says so rather than guessing which."
      ]
    }
  ],
  "faqs": [
    {
      "q": "What do the four ritual/1 transitions do?",
      "a": "observe records a performed liturgy; witness attaches a corroborating attestation; consecrate turns a witnessed observance into one that carries consequence; project reads the fragment's current state, including how much of what was observed actually carries consequence."
    },
    {
      "q": "How do you correct a wrongly-recorded observance?",
      "a": "You cannot edit or delete one — there is no API for either. The fix is a new observance that supersedes the old one, the same append-only discipline the estate holds for shipped/1: a correction is appended, never edited."
    },
    {
      "q": "What does consecrate() refuse, with no way to override it?",
      "a": "Anything but a person/ identity, and any observance that has not yet been witnessed. Both throw unconditionally — there is no flag to consecrate anyway, because that flag is exactly the shortcut the ladder is built to close off."
    }
  ],
  "related": [
    {
      "label": "ritual/1: the Present Tense",
      "href": "/academy/curriculum/ritual-the-present-tense"
    },
    {
      "label": "What ritual/1 Refuses, By Design",
      "href": "/academy/curriculum/ritual-what-it-refuses"
    },
    {
      "label": "The Two Tenses",
      "href": "/academy/curriculum/the-two-tenses"
    }
  ]
}