# v0.7.0 Integrated Release Validation Report

## Metadata

| Field | Value |
|-------|-------|
| Scope | 0.7.0 Integrated Release Gates Validation |
| Date | 2026-05-20 |
| Executor | Kiro (AI agent) |
| Coverage | Integration capstone for Fuzzing Foundation, ClusterFuzzLite + Corpus, Package Compatibility, Release Workflow |
| AGENTS.md Version | 0.7.0 |

---

## Sub-Spec Status Summary

| Component | Name | Status | Main Changed Files |
|-----------|------|--------|-------------------|
| Fuzzing Foundation | Fuzz targets + infrastructure | complete | `fuzz/fuzz_targets/*.rs`, `fuzz/Cargo.toml`, `fuzz/corpus/`, `fuzz/README.md`, Makefile (`fuzz-smoke`, `test-rust-fuzz-smoke`) |
| ClusterFuzzLite + Corpus | CI fuzzing + corpus management | complete | `.github/workflows/cflite_pr.yml`, `.github/workflows/cflite_batch.yml`, `.github/workflows/cflite_cron.yml`, `.clusterfuzzlite/` (Dockerfile, build.sh, project.yaml), harness rules FUZZ-001..007 |
| Package Compatibility | NGINX module packaging | complete | `docs/guides/PACKAGE_INSTALLATION.md`, `docs/guides/NGINX_COMPATIBILITY.md`, `packaging/nfpm/`, release matrix documentation |
| Release Workflow | Package build + distribution | complete | `.github/workflows/release-packages.yml`, `packaging/scripts/smoke-test-basic.sh`, SHA256SUMS generation logic, `docs/guides/PACKAGE_DISTRIBUTION.md` |

---

## Cross-Spec Impact Summary

### Release Gates

- Fuzz targets existence and buildability gate (Fuzzing Foundation)
- Fuzz smoke pass gate via `make test-rust-fuzz-smoke` (Fuzzing Foundation)
- ClusterFuzzLite PR workflow existence gate (ClusterFuzzLite + Corpus)
- Nightly batch fuzz workflow existence gate (ClusterFuzzLite + Corpus)
- Corpus pruning mechanism existence gate (ClusterFuzzLite + Corpus)
- Fuzz guide completeness gate (Fuzzing Foundation, ClusterFuzzLite + Corpus)
- Release package workflow existence gate (Release Workflow)
- .deb/.rpm naming with NGINX version component gate (Package Compatibility)
- SHA256SUMS generation logic existence gate (Release Workflow)
- Install/compatibility documentation completeness gate (Package Compatibility)
- Package smoke test job existence gate (Release Workflow)
- All new rules covered by harness-check gate (ClusterFuzzLite + Corpus)

### Harness Rules

- FUZZ-001: Converter adjacent change assessment (Advisory)
- FUZZ-002: New logic must have fuzz coverage (Advisory)
- FUZZ-003: Target deterministic execution (Mandatory)
- FUZZ-004: Crash minimization process (Mandatory)
- FUZZ-005: Batch paired with pruning (Mandatory)
- FUZZ-006: Pure documentation changes skip fuzz (Mandatory)
- FUZZ-007: Infrastructure passes harness-check (Mandatory)

### Documentation

- `fuzz/README.md` — Fuzz testing guide (local running, corpus, crash analysis, contribution workflow, harness rules)
- `docs/guides/PACKAGE_INSTALLATION.md` — Prebuilt package installation guide
- `docs/guides/NGINX_COMPATIBILITY.md` — NGINX dynamic module compatibility
- `docs/guides/PACKAGE_DISTRIBUTION.md` — Package distribution (artifact naming, SHA256SUMS, GPG)
- `docs/project/release-gates/0.7.0-release-gates.md` — 0.7.0 release gate definitions
- `docs/project/release-gates/v070-gates.md` — v0.7.0 gate validation reference

### CI Workflows

- `.github/workflows/cflite_pr.yml` — ClusterFuzzLite PR fuzzing (path-filtered)
- `.github/workflows/cflite_batch.yml` — Nightly batch fuzzing
- `.github/workflows/cflite_cron.yml` — Corpus pruning (weekly)
- `.github/workflows/release-packages.yml` — Release package build + smoke test

### Makefile Targets

- `fuzz-smoke` — 30-second smoke run for fuzz targets
- `test-rust-fuzz-smoke` — Quick 5-second check for all fuzz targets

### Test Suites

- `fuzz/fuzz_targets/convert_html.rs` — HTML conversion fuzzing
- `fuzz/fuzz_targets/streaming_chunks.rs` — Streaming chunk boundary fuzzing
- `fuzz/fuzz_targets/negotiation_and_headers.rs` — Accept negotiation fuzzing
- `fuzz/fuzz_targets/parser_html.rs` — HTML parser edge cases
- `fuzz/fuzz_targets/ffi_convert.rs` — FFI boundary fuzzing
- `fuzz/fuzz_targets/security_validator.rs` — Security validation fuzzing
- `fuzz/fuzz_targets/fuzz_streaming_no_panic.rs` — Streaming panic-freedom
- `fuzz/fuzz_targets/fuzz_streaming_chunk_split.rs` — Arbitrary chunk split points
- `packaging/scripts/smoke-test-basic.sh` — Package installation smoke test

---

## Verification Matrix Results

| ID | Command | Layer | Status | Key Metric |
|----|---------|-------|--------|------------|
| VM-01 | `make harness-check` | L1 | PASS | 15 checks pass |
| VM-02 | `make harness-check-full` | L1 | PASS | All sub-checks pass |
| VM-03 | `make docs-check` | L1 | PASS | 173 files, 0 errors |
| VM-04 | `make release-gates-check` | L1 | PASS | 14 passed |
| VM-05 | `make release-gates-check-070` | L1 | PASS | All gates pass |
| VM-06 | `make release-gates-check-strict` | L1 | PASS | 39+23 passed |
| VM-07 | `make test-rust` | L2 | PASS | 1231 tests, 0 failed |
| VM-08 | `make test-nginx-unit` | L2 | PASS | 615 assertions |
| VM-09 | `make test-e2e-rust` + `verify-chunked-native-e2e-smoke` | L2 | PASS | 6 E2E cases |
| VM-10 | `make coverage-rust` | L3 | PASS | 91.4%/93.6% lines |
| VM-11 | `make coverage-c` | L3 | PASS | 80.5% lines |
| VM-12 | `make test-rust-fuzz-smoke` | L3 | PASS | 8 targets, 0 crashes |
| VM-13 | Package smoke test | L4 | DEFERRED | Environment constraint |

**Summary**: 12/13 commands PASS, 1 DEFERRED (non-critical).

---

## Risk Coverage

### Fuzz Target Attack Surface Coverage

| Target | Attack Surfaces Covered |
|--------|------------------------|
| `convert_html` | HTML parsing, sanitizer rules, emitter output, void element handling, nesting depth |
| `streaming_chunks` | Chunk boundaries, state machine transitions, UTF-8 cross-boundary, backpressure paths |
| `negotiation_and_headers` | Accept header negotiation, header parsing, cache variant selection |
| `parser_html` | HTML parser edge cases, malformed input, tag soup recovery |
| `ffi_convert` | FFI boundary crossing, memory safety at C/Rust interface, error propagation |
| `security_validator` | URL validation, control character rejection, injection prevention |
| `fuzz_streaming_no_panic` | Streaming converter panic-freedom under arbitrary input |
| `fuzz_streaming_chunk_split` | Arbitrary chunk split points, partial input handling |

### Coverage Assessment

All critical input-processing code paths have dedicated fuzz targets:
- **Parser layer**: `convert_html`, `parser_html` cover HTML parsing
- **Streaming layer**: `streaming_chunks`, `fuzz_streaming_no_panic`, `fuzz_streaming_chunk_split` cover streaming paths
- **FFI boundary**: `ffi_convert` covers the C/Rust interface
- **Security surface**: `security_validator` covers input validation
- **Protocol layer**: `negotiation_and_headers` covers Accept negotiation

---

## Corpus Strategy Summary

| Category | Storage Location | Committed to Main | Lifecycle |
|----------|-----------------|-------------------|-----------|
| Seed Corpus | `fuzz/corpus/<target>/` | Yes | Permanent (manually maintained) |
| Generated Corpus | `<repo>-corpus` repository main branch | No | Auto-managed (pruned weekly) |
| Crash Artifacts | GitHub Actions Workflow Artifacts | No | 90 days (GitHub default) |
| Minimized Regression | `fuzz/corpus/<target>/regression_*.bin` | Yes | Permanent (fix verification) |
| Coverage Corpus | `<repo>-corpus` repository coverage branch | No | Auto-managed by ClusterFuzzLite |

**Key principles**:
- Seed corpus provides meaningful starting coverage; kept small (under 1KB per file)
- Generated corpus grows via CI batch fuzzing; pruned weekly to prevent bloat
- Crash artifacts are ephemeral; only minimized regressions are permanent
- Regression corpus ensures bugs stay fixed across future changes

---

## Crash Regression Process Summary

1. **Discovery**: Crash artifact found by CI fuzzing (ClusterFuzzLite batch or PR workflow)
2. **Download**: Retrieve crash artifact from GitHub Actions workflow run
3. **Reproduction**: `cargo +nightly fuzz run <target> <crash_file>` confirms the crash locally
4. **Minimization**: `cargo +nightly fuzz tmin <target> <crash_file>` reduces to minimal reproducer
5. **Security Assessment**: Sanitizer reports (ASan/UBSan/MSan) classify as security defects
6. **Fix Implementation**: Root cause identified and fixed in source code
7. **Regression Commit**: Minimized input committed to `fuzz/corpus/<target>/regression_<description>.bin`
8. **Verification**: Confirm target no longer crashes on the regression input
9. **Issue Closure**: Only after regression input is committed and CI passes

**Security defect handling**: Findings from sanitizer reports follow the project's private security vulnerability reporting process. Crash artifacts triggering sanitizer reports are NOT committed to public branches.

---

## Package Smoke Test Strategy Summary

### Basic Smoke Test

The basic smoke test (`packaging/scripts/smoke-test-basic.sh`) validates:
- Package installation succeeds (`dpkg -i` for .deb, `rpm -i` for .rpm)
- `nginx -t` configuration test passes with the module loaded
- Module can be loaded via `load_module` directive

### Full Smoke Test (CI)

The full CI smoke test (defined in `release-packages.yml`) validates across a matrix of containers:
- ubuntu:22.04, ubuntu:24.04, debian:12, almalinux:9, amazonlinux:2023
- Package install + NGINX start + HTTP request verification
- Module functionality confirmed via curl response

### Execution Strategy

- **Local**: Not executable (requires Linux containers, pre-built packages, nFPM)
- **CI**: Runs automatically on tag push (`v*`) and manual `workflow_dispatch`
- **Release gate**: `make release-gates-check-070` verifies smoke test job exists in workflow

---

## Deferred Items

| Item | Command | Reason | Risk | Alternative Verification | Follow-up Path |
|------|---------|--------|------|--------------------------|----------------|
| Package smoke test | `packaging/scripts/smoke-test-basic.sh <PKG> <VER>` | Cannot execute locally — requires pre-built .deb/.rpm packages, nFPM, Linux NGINX source build, and Linux container environment | LOW | (a) `bash -n` syntax check passes, (b) CI workflow defines smoke-test job across 5 containers, (c) Release gate verifies workflow structure | Executed automatically in CI on tag push (v*) or manual workflow_dispatch |

**Critical-level deferred items**: NONE

---

## Harness Compliance Statement

This spec's execution did NOT weaken any harness rules, release gate checks, or docs-check validators. All verification passes are based on actual correctness of the codebase, not rule relaxation.

Specifically confirmed:
- No harness-check rules were removed or weakened
- No release-gate validators were modified to skip checks
- No docs-check rules were relaxed to ignore errors
- No tracked files were excluded via .gitignore to avoid validation
- All FUZZ-001 through FUZZ-007 rules remain enforced at their defined severity levels

---

## Commit List

| # | Hash | Message | Category |
|---|------|---------|----------|
| 1 | c5820d56 | chore(harness): add fuzz-infrastructure rules and reorganize fuzz docs | harness |
| 2 | dbb13f2f | fix(gate): add validate_fuzz_packaging_070 and fix release gate validators | fix |
| 3 | de8591f1 | docs(release): add compatibility, distribution, and gate docs for 0.7.0 | docs |
| 4 | 3b95499a | docs(release): add 0.7.0 integrated release validation report | docs |

---

## Push Result

| Field | Value |
|-------|-------|
| Branch | dev/wip-0.7.0 |
| Remote | origin (github.com:cnkang/nginx-markdown-for-agents.git) |
| Status | success (9653fa6b..3b95499a) |

---

## Acceptance Gate

| Criterion | Status |
|-----------|--------|
| Layer 1 — All 6 commands PASS | ✅ PASS |
| Layer 2 — All 3 commands PASS | ✅ PASS |
| Layer 3 — All 3 commands PASS or documented deferral | ✅ PASS |
| Layer 4 — PASS or documented environment constraint | ✅ DEFERRED (documented, LOW risk) |
| Completion report generated and passes docs-check | ✅ PASS (confirmed) |
| No critical-level deferred items | ✅ None |
| No rules weakened during execution | ✅ Confirmed |

**Overall Acceptance Gate: PASSED**

Final verification run (2026-05-20):
- `make harness-check` → exit 0 (15/15 checks PASS)
- `make release-gates-check-070` → exit 0 (all gates PASS)
- `make docs-check` → exit 0 (no errors)
