docs: align lifecycle wording and extend version checks

CHANGELOG.md

@@ -5,6 +5,10 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## Unreleased
 
+### Changed
+
+- docs/versioning: clarified that the current public drawlist pins are v1 and v2 only; older alpha entries below do not override the current pins in `include/zr/zr_version.h`.
+
 ## 1.3.8-alpha.8 — 2026-02-26
 
 ### Fixed

README.md

@@ -9,7 +9,7 @@
 <p align="center">
   <a href="https://github.com/RtlZeroMemory/Zireael/actions/workflows/ci.yml"><img src="https://github.com/RtlZeroMemory/Zireael/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://github.com/RtlZeroMemory/Zireael/releases"><img src="https://img.shields.io/github/v/release/RtlZeroMemory/Zireael" alt="Release"></a>
-  <a href="https://rtlzeromemory.github.io/Zireael/release-model/"><img src="https://img.shields.io/badge/status-pre--alpha-orange" alt="Status: Pre-alpha"></a>
+  <a href="https://rtlzeromemory.github.io/Zireael/release-model/"><img src="https://img.shields.io/badge/status-alpha-orange" alt="Status: Alpha"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
   <a href="https://rtlzeromemory.github.io/Zireael/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue" alt="Docs"></a>
 </p>
@@ -94,7 +94,7 @@ capabilities.
 
 ## Project Status
 
-Zireael is currently **pre-alpha**.
+Zireael is currently **alpha**.
 
 -   APIs and wire formats are versioned, but still evolving
 -   Pre-GA iteration is active
@@ -230,7 +230,7 @@ Current pins (from `include/zr/zr_version.h`):
 
 -   Library: 1.3.8
 -   Engine ABI: 1.2.0
--   Drawlist formats: v1
+-   Drawlist formats: v1, v2
 -   Event batch format: v1
 
 Version pins are determinism-critical and must not be overridden.

docs/ABI_REFERENCE.md

@@ -22,7 +22,7 @@ Pinned versions:
 
 Binary formats:
 
-- `include/zr/zr_drawlist.h` (drawlist v1)
+- `include/zr/zr_drawlist.h` (drawlist v1/v2)
 - `include/zr/zr_event.h` (packed event batch v1)
 
 ## Result / error model
@@ -75,7 +75,7 @@ Canonical source:
 - Reserved/padding fields in v1 structs **MUST be 0** when passed by the caller.
 - `ZR_EV_TEXT.codepoint` carries Unicode scalar values; invalid UTF-8 input emits U+FFFD.
 
-Drawlist v1 and event batch v1 are specified by:
+Drawlist v1/v2 and event batch v1 are specified by:
 
 - `docs/modules/DRAWLIST_FORMAT_AND_PARSER.md`
 - `docs/modules/EVENT_SYSTEM_AND_PACKED_EVENT_ABI.md`

docs/VERSION_PINS.md

@@ -4,7 +4,7 @@ This file is the human-readable mirror of `include/zr/zr_version.h`.
 
 ## Status
 
-Zireael is pre-alpha. ABI and wire-format details may change between releases.
+Zireael is alpha. ABI and wire-format details may change between releases.
 
 ## Library
 

docs/modules/CONFIG_AND_ABI_VERSIONING.md

@@ -21,19 +21,24 @@ See also:
 `engine_create()` takes `zr_engine_config_t`, which includes requested versions for:
 
 - engine ABI (`ZR_ENGINE_ABI_*`)
-- drawlist format (`ZR_DRAWLIST_VERSION_V1`, `ZR_DRAWLIST_VERSION_V1`, `ZR_DRAWLIST_VERSION_V1`, or
-  `ZR_DRAWLIST_VERSION_V1`, `ZR_DRAWLIST_VERSION_V1`)
+- drawlist format (`ZR_DRAWLIST_VERSION_V1` or `ZR_DRAWLIST_VERSION_V2`)
 - packed event batch format (`ZR_EVENT_BATCH_VERSION_V1`)
 
 Negotiation rules:
 
 - Requested engine ABI and event batch versions MUST match pinned versions exactly.
-- Drawlist version MUST be one of the supported pinned versions (`ZR_DRAWLIST_VERSION_V1`, `ZR_DRAWLIST_VERSION_V1`,
-  `ZR_DRAWLIST_VERSION_V1`, `ZR_DRAWLIST_VERSION_V1`, or `ZR_DRAWLIST_VERSION_V1`).
+- Drawlist version MUST be one of the supported pinned versions (`ZR_DRAWLIST_VERSION_V1` or
+  `ZR_DRAWLIST_VERSION_V2`).
 - If any requested version is not supported, `engine_create()` fails with `ZR_ERR_UNSUPPORTED` and performs no partial effects.
 
 Pinned versions are defined in `include/zr/zr_version.h`.
 
+Current drawlist-version behavior:
+
+- `ZR_DRAWLIST_VERSION_V1` is the baseline format.
+- `ZR_DRAWLIST_VERSION_V2` is additive and enables `ZR_DL_OP_BLIT_RECT`.
+- Versions above the current pins are rejected at config validation time.
+
 ## Config structs (public ABI)
 
 Defined in `src/core/zr_config.h`.

docs/modules/DRAWLIST_FORMAT_AND_PARSER.md

@@ -4,7 +4,11 @@ This module documents ZRDL ingestion in the engine.
 
 ## Supported Version
 
-Only `ZR_DRAWLIST_VERSION_V1` is accepted.
+`ZR_DRAWLIST_VERSION_V1` and `ZR_DRAWLIST_VERSION_V2` are accepted.
+
+`ZR_DRAWLIST_VERSION_V1` is the baseline format. `ZR_DRAWLIST_VERSION_V2`
+is additive and only gates `ZR_DL_OP_BLIT_RECT`; the other currently pinned
+opcodes, including `DRAW_CANVAS` and `DRAW_IMAGE`, remain valid in v1.
 
 ## Frame Structure
 
@@ -38,7 +42,8 @@ persistent stores:
 
 If a draw command references an unknown ID, execution fails.
 
-## No Backward Compatibility
+## Version-Rejection Behavior
 
-Legacy multi-version paths were removed. The parser/executor are single-version
-(v1) by design.
+Versions outside the current pinned set are rejected. The parser/executor share
+the same core path for v1/v2 and do not retain legacy experimental negotiation
+paths beyond the current public pins.

scripts/check_version_pins.py

@@ -14,6 +14,7 @@
 
 
 RE_DEFINE_U = re.compile(r"^\s*#define\s+(ZR_[A-Z0-9_]+)\s+\((\d+)u\)\s*$")
+RE_WS = re.compile(r"\s+")
 
 
 def parse_pins(text: str) -> dict[str, int]:
@@ -32,11 +33,19 @@ def require(pins: dict[str, int], name: str) -> int:
   return pins[name]
 
 
+def normalize_ws(text: str) -> str:
+  return RE_WS.sub(" ", text).strip()
+
+
 def main() -> int:
   repo_root = pathlib.Path(__file__).resolve().parents[1]
   header = repo_root / "include" / "zr" / "zr_version.h"
+  readme = repo_root / "README.md"
   docs_pins = repo_root / "docs" / "VERSION_PINS.md"
   docs_versioning = repo_root / "docs" / "abi" / "versioning.md"
+  docs_abi_reference = repo_root / "docs" / "ABI_REFERENCE.md"
+  docs_config_module = repo_root / "docs" / "modules" / "CONFIG_AND_ABI_VERSIONING.md"
+  docs_drawlist_module = repo_root / "docs" / "modules" / "DRAWLIST_FORMAT_AND_PARSER.md"
 
   header_text = header.read_text(encoding="utf-8")
   pins = parse_pins(header_text)
@@ -71,6 +80,9 @@ def main() -> int:
 
   # --- docs/VERSION_PINS.md must mention exact macro values ---
   pins_text = docs_pins.read_text(encoding="utf-8")
+  if "Zireael is alpha." not in pins_text:
+    print(f"{docs_pins}: missing alpha lifecycle status text", file=sys.stderr)
+    return 1
   for k in required:
     v = pins[k]
     if re.search(rf"\b{re.escape(k)}\s*=\s*{v}\b", pins_text) is None:
@@ -85,6 +97,59 @@ def main() -> int:
   if f"Engine ABI: v{abi_ver[0]}.{abi_ver[1]}.{abi_ver[2]}" not in versioning_text:
     print(f"{docs_versioning}: missing engine ABI version v{abi_ver[0]}.{abi_ver[1]}.{abi_ver[2]}", file=sys.stderr)
     return 1
+  if "Lifecycle: alpha" not in versioning_text:
+    print(f"{docs_versioning}: missing alpha lifecycle status text", file=sys.stderr)
+    return 1
+  if "Drawlist formats: v1, v2" not in versioning_text:
+    print(f"{docs_versioning}: missing drawlist version snapshot for v1, v2", file=sys.stderr)
+    return 1
+
+  # --- README.md must reflect the current lifecycle and drawlist snapshot ---
+  readme_text = readme.read_text(encoding="utf-8")
+  if "status-alpha" not in readme_text:
+    print(f"{readme}: missing alpha status badge", file=sys.stderr)
+    return 1
+  if "Zireael is currently **alpha**." not in readme_text:
+    print(f"{readme}: missing alpha lifecycle status text", file=sys.stderr)
+    return 1
+  if "Drawlist formats: v1, v2" not in readme_text:
+    print(f"{readme}: missing drawlist version snapshot for v1, v2", file=sys.stderr)
+    return 1
+
+  # --- docs/ABI_REFERENCE.md must describe the current public drawlist header scope ---
+  abi_reference_text = docs_abi_reference.read_text(encoding="utf-8")
+  expected_abi_reference_snippets = [
+    "`include/zr/zr_drawlist.h` (drawlist v1/v2)",
+    "Drawlist v1/v2 and event batch v1 are specified by:",
+  ]
+  for snippet in expected_abi_reference_snippets:
+    if snippet not in abi_reference_text:
+      print(f"{docs_abi_reference}: missing current ABI drawlist wording: {snippet!r}", file=sys.stderr)
+      return 1
+
+  # --- docs/modules/CONFIG_AND_ABI_VERSIONING.md must describe current drawlist pins ---
+  config_module_text = docs_config_module.read_text(encoding="utf-8")
+  expected_config_snippets = [
+    "drawlist format (`ZR_DRAWLIST_VERSION_V1` or `ZR_DRAWLIST_VERSION_V2`)",
+    "Drawlist version MUST be one of the supported pinned versions (`ZR_DRAWLIST_VERSION_V1` or\n  `ZR_DRAWLIST_VERSION_V2`).",
+  ]
+  config_module_text_normalized = normalize_ws(config_module_text)
+  for snippet in expected_config_snippets:
+    if normalize_ws(snippet) not in config_module_text_normalized:
+      print(f"{docs_config_module}: missing current drawlist-version wording: {snippet!r}", file=sys.stderr)
+      return 1
+
+  # --- docs/modules/DRAWLIST_FORMAT_AND_PARSER.md must describe current parser support ---
+  drawlist_module_text = docs_drawlist_module.read_text(encoding="utf-8")
+  expected_drawlist_snippets = [
+    "`ZR_DRAWLIST_VERSION_V1` and `ZR_DRAWLIST_VERSION_V2` are accepted.",
+    "`ZR_DRAWLIST_VERSION_V2`\nis additive and only gates `ZR_DL_OP_BLIT_RECT`;",
+  ]
+  drawlist_module_text_normalized = normalize_ws(drawlist_module_text)
+  for snippet in expected_drawlist_snippets:
+    if normalize_ws(snippet) not in drawlist_module_text_normalized:
+      print(f"{docs_drawlist_module}: missing current parser-version wording: {snippet!r}", file=sys.stderr)
+      return 1
 
   return 0
 

tests/golden/fixtures/blit_drawlist_canvas_001_ascii/case.txt

@@ -1,6 +1,6 @@
 id: blit_drawlist_canvas_001_ascii
 kind: drawlist-opcode
-opcode: DRAW_CANVAS(v4)
+opcode: DRAW_CANVAS(v1)
 blitter: ascii
 input: 1x1 RGBA pixel (12,34,56,255)
 expected: space glyph with fg/bg=0x000C2238