Update Kida component validation and parity (#114)

Author: lbliii

Makefile

@@ -4,7 +4,7 @@
 PYTHON_VERSION ?= 3.14t
 VENV_DIR ?= .venv
 
-.PHONY: all help setup install test test-cov test-thread test-async lint lint-fix format ty clean shell docs docs-serve build publish release gh-release action-tag
+.PHONY: all help setup install test test-cov test-thread test-async test-safety test-rc-safety lint lint-fix format format-check ty package-smoke verify-stability verify-rc clean shell docs docs-serve build publish release gh-release action-tag
 
 all: help
 
@@ -20,10 +20,15 @@ help:
 	@echo "  make test-cov   - Run tests with coverage report"
 	@echo "  make test-thread - Run thread safety stress tests"
 	@echo "  make test-async - Run async feature tests"
+	@echo "  make test-safety - Run focused safety/concurrency tests"
 	@echo "  make lint       - Run ruff linter"
 	@echo "  make lint-fix   - Run ruff linter with auto-fix"
 	@echo "  make format     - Run ruff formatter"
+	@echo "  make format-check - Check ruff formatting"
 	@echo "  make ty         - Run ty type checker (fast, Rust-based)"
+	@echo "  make package-smoke - Build artifacts and smoke-test installed wheel"
+	@echo "  make verify-stability - Run the full local stability gate"
+	@echo "  make verify-rc  - Alias for verify-stability"
 	@echo "  make docs       - Build documentation site (requires bengal)"
 	@echo "  make docs-serve - Start dev server for docs (requires bengal)"
 	@echo "  make build      - Build distribution packages"
@@ -50,7 +55,7 @@ test:
 	uv run pytest -q --tb=short
 
 test-cov:
-	uv run pytest --cov=src/kida --cov-report=term-missing
+	uv run pytest --cov=kida --cov-report=term-missing --cov-fail-under=83
 
 test-thread:
 	@echo "Running thread safety stress tests..."
@@ -60,6 +65,18 @@ test-async:
 	@echo "Running async feature tests..."
 	PYTHON_GIL=0 uv run pytest tests/test_kida_async_features.py -v --tb=short
 
+test-safety:
+	@echo "Running focused safety/concurrency tests..."
+	PYTHON_GIL=0 uv run pytest \
+		tests/test_render_surface_parity.py \
+		tests/test_sandbox_fuzz.py \
+		tests/test_bytecode_cache_concurrency.py \
+		tests/test_lru_cache_concurrency.py \
+		tests/test_kida_stress_test.py \
+		-q --tb=short
+
+test-rc-safety: test-safety
+
 lint:
 	@echo "Running ruff linter..."
 	uv run ruff check src/ tests/
@@ -72,10 +89,23 @@ format:
 	@echo "Running ruff formatter..."
 	uv run ruff format src/ tests/
 
+format-check:
+	@echo "Checking ruff formatting..."
+	uv run ruff format --check src/ tests/
+
 ty:
 	@echo "Running ty type checker (Astral, Rust-based)..."
 	uv run ty check src/kida/
 
+package-smoke:
+	@echo "Building and smoke-testing package artifacts..."
+	uv run python scripts/package_smoke.py
+
+verify-stability: lint format-check ty test-cov test-safety package-smoke
+	@echo "✓ Stability verification gate passed"
+
+verify-rc: verify-stability
+
 docs:
 	@echo "Building documentation site..."
 	uv sync --group docs

docs/stability-gate.md

@@ -0,0 +1,74 @@
+# Kida Stability Gate
+
+Use this checklist when a change touches public contracts, diagnostics,
+packaging, render surfaces, sandbox behavior, or free-threading assumptions.
+It is a project ritual for keeping Kida boring in production, not a promise
+that a major release is imminent.
+
+## Local Stability Gate
+
+Run the full local gate:
+
+```bash
+make verify-stability
+```
+
+This runs lint, format check, `ty`, full pytest with `--cov-fail-under=83`,
+focused render/sandbox/concurrency safety tests under `PYTHON_GIL=0`, and a
+wheel/sdist build plus clean-venv package smoke test.
+
+`make verify-rc` remains an alias for contributors who already use that name.
+
+The package smoke test verifies:
+
+- import from the installed wheel
+- template render
+- CLI `check --validate-calls`
+- CLI `components --json`
+- component metadata
+- sandbox denial for blocked reflection attributes
+
+## Benchmark Evidence
+
+Linux 3.14t benchmark baselines are the performance comparison baseline. Darwin
+or other local baselines are useful for development, but they must not replace
+the committed Linux baseline used by CI.
+
+Refresh the Linux baseline with the existing workflow or on a Linux 3.14t host:
+
+```bash
+./scripts/benchmark_baseline.sh baseline
+```
+
+Compare a candidate against the committed baseline:
+
+```bash
+./scripts/benchmark_compare.sh baseline
+```
+
+For stricter stability evidence, run the benchmark families that cover the
+main runtime promises:
+
+```bash
+uv run pytest \
+  benchmarks/test_benchmark_compile_pipeline.py \
+  benchmarks/test_benchmark_render.py \
+  benchmarks/test_benchmark_streaming.py \
+  benchmarks/test_benchmark_inherited_blocks.py \
+  benchmarks/test_benchmark_concurrent.py \
+  --benchmark-only -v
+```
+
+Regression thresholds:
+
+- fail on more than 5% compile/render/stream regression
+- fail on more than 10% concurrency regression
+- update the Linux baseline only with an explicit baseline drift rationale
+
+Include benchmark evidence in the PR when it matters:
+
+- Linux platform and Python build
+- GIL status
+- benchmark command
+- compare summary
+- any baseline updates and why they are safe

plan/epic-pre-1.0-stabilization.md

@@ -0,0 +1,123 @@
+# Kida Pre-1.0 Stabilization Rituals
+
+Kida is moving from pre-1.0 feature turbulence to a framework-author-ready
+surface. This is not a plan to cut a major release candidate; it is a plan to
+turn the behaviors framework authors already depend on into visible, repeatable
+project rituals. The stabilization posture is deliberately conservative: no new
+runtime dependencies, public APIs, template tags, or config knobs unless they
+are required to close a bug that blocks real users.
+
+Current baseline after the `0.8.0` work on `main`:
+
+- Pure Python remains the default contract; runtime dependencies stay empty.
+- `make lint`, `make ty`, and the full test suite are the required local gates.
+- Coverage currently targets the project floor in `pyproject.toml`; the
+  stability gate should enforce the current 83% floor.
+- Existing strict xfails should stay at zero for stabilization work.
+
+## Phase 1: Stability Inventory and API Snapshot
+
+Freeze the public framework-author surface before changing behavior.
+
+- Add a public API snapshot test for:
+  - `kida.__all__`
+  - `ErrorCode` names and values
+  - `Environment.__init__`
+  - public `Template` render and metadata methods
+  - metadata dataclass fields
+  - CLI subcommands and flags
+- Update API and CLI docs to name stable surfaces and separate them from
+  internal or still-provisional surfaces.
+- Treat snapshot changes as deliberate API changes that require changelog and
+  docs updates in the same PR.
+
+Acceptance:
+
+- `make lint`, `make ty`, and focused tests pass.
+- Snapshot tests fail when public contracts drift.
+
+## Phase 2: Component and Metadata Contract Tests
+
+Harden component validation and metadata for framework integration.
+
+- Extend imported def validation tests for aliases, missing required props,
+  unknown props, literal type mismatches, missing imported templates, and
+  dynamic import skip behavior.
+- Stabilize metadata across `list_defs()`, `def_metadata()`,
+  `block_metadata()`, `template_metadata()`, inheritance, regions, slots, and
+  CLI JSON output.
+- Ensure `K-CMP-001` and `K-CMP-002` have docs entries with fix guidance.
+
+Acceptance:
+
+- Imported literal component validation is covered end to end.
+- Dynamic imports are explicitly documented as skipped.
+
+## Phase 3: Render, Sandbox, and Free-Threading Gates
+
+Convert safety invariants into local verification gates.
+
+- Add render-surface coverage meta-tests for every current render surface.
+- Assert there are no active strict xfails.
+- Add a fragment-render scaffold guard so block/fragment render methods use the
+  shared scaffold path.
+- Promote sandbox fuzz, bytecode-cache concurrency, LRU concurrency, and render
+  stress tests into stability verification.
+
+Acceptance:
+
+- `PYTHON_GIL=0 make verify-stability` passes locally on 3.14t.
+- Free-threaded shared state has an audit note for intentional sharing,
+  locking, and copy-on-write behavior.
+
+## Phase 4: Diagnostics and Docs Truth Audit
+
+Make docs match actual behavior.
+
+- Add an ErrorCode docs coverage test for every public `ErrorCode`, including
+  `K-CMP-*`.
+- Snapshot representative `kida check --validate-calls`,
+  `kida components --json`, and error/warning formatting.
+- Reconcile API, CLI, components, type-checking, sandbox, thread-safety, and
+  Jinja2 migration docs with current behavior.
+
+Acceptance:
+
+- Every public diagnostic has docs, fix guidance, and stable formatting.
+
+## Phase 5: Benchmark Baseline and Packaging Smoke
+
+Collect performance evidence and package smoke tests.
+
+- Refresh Linux 3.14t benchmark baselines using existing benchmark scripts for
+  render, compile pipeline, streaming, inherited blocks, and concurrency.
+- Add benchmark comparison instructions to release docs.
+- Build wheel/sdist, install from the wheel in a clean temporary environment,
+  and smoke-test import, render, CLI check, component metadata, and sandbox
+  denial.
+- Fail the stability gate on more than 5% compile/render/stream regression or more than 10%
+  concurrency regression versus the committed Linux 3.14t baseline unless the
+  PR updates the baseline with justification.
+
+Acceptance:
+
+- Any user-facing behavior change has docs or changelog coverage.
+- The repo has enough evidence to make a release decision later without
+  reconstructing what was tested.
+
+## Stability Gate Target
+
+`make verify-stability` should become the single local stabilization gate and
+run:
+
+- `ruff check`
+- `ruff format --check`
+- `ty`
+- full pytest
+- coverage with `--cov-fail-under=83`
+- sandbox fuzz and thread-safety tests
+- `PYTHON_GIL=0` free-threading pass where supported
+- wheel build/install smoke test
+
+`make verify-rc` may remain as an alias, but the ritual is about stability
+evidence rather than committing the project to a specific version tag.