# `@neith/release`

Release management primitives for Phase 52: release pipelines, distribution,
platform publishing, benchmark-enforced performance gates, and web-accessibility
audits.

Full package documentation now lives under `docs/domains/neith/release/`:

- `docs/domains/neith/release/README.md`
- `docs/domains/neith/release/developer-guide.md`
- `docs/domains/neith/release/user-guide.md`
- `docs/domains/neith/release/api/README.md`
- `docs/domains/neith/release/runbook.md`
- `docs/domains/neith/release/training/README.md`
- `docs/domains/neith/release/documentation-coverage.md`

## Performance Benchmarks

Phase 52's first unchecked completion criterion requires release and
distribution performance benchmarks that meet explicit budgets. This package now
enforces that with `tests/performance.benchmark.spec.ts`.

The benchmark suite covers six representative hot paths:

| Scenario                                | Scope                                                                                 | Budget shape                   |
| --------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------ |
| `pipeline-config-materialization`       | Build stable release train configs and workflow YAML                                  | avg/op, p95 iteration, ops/sec |
| `pipeline-run-execution`                | Execute full release runs via the in-memory step runner                               | avg/op, p95 iteration, ops/sec |
| `distribution-download-page-generation` | Generate dense multi-platform download pages                                          | avg/op, p95 iteration, ops/sec |
| `auto-update-check-resolution`          | Resolve update metadata and semver upgrade decisions                                  | avg/op, p95 iteration, ops/sec |
| `feature-gate-bulk-evaluation`          | Evaluate high-cardinality release targeting rules                                     | avg/op, p95 iteration, ops/sec |
| `platform-artifact-materialization`     | Materialize packaging metadata for Linux, Windows, macOS, Docker, and AWS Marketplace | avg/op, p95 iteration, ops/sec |

These budgets are encoded in `src/performance/release-benchmarks.ts` and
validated by Vitest. The thresholds are intentionally aligned to fast
control-plane expectations for release tooling: sub-millisecond average latency
for most in-memory generation paths, low-double-digit millisecond p95 per batch,
and throughput floors high enough to catch obvious regressions.

## Performance Regression Guard

Phase 52 also requires measured performance regression to stay below 5%.
`@neith/release` now certifies that separately from the absolute benchmark
budgets.

The regression guard uses three stabilized benchmark samples and compares the
median metrics for each scenario against the certified baseline ledger in
`src/performance/release-benchmarks.ts`. Latency metrics may not regress by more
than 5%, and throughput may not fall by more than 5%.

This catches real drift without overreacting to single-run jitter on the most
p95-sensitive paths, especially the high-cardinality feature-gate scenario. The
baseline ledger is calibrated from the real Vitest benchmark target rather than
from ad hoc local script timings, so the regression gate reflects the exact CI
execution surface that enforces it.

Run the suite with:

```bash
pnpm --filter @neith/release run benchmark
```

Or through Nx:

```bash
pnpm nx run @neith/release:benchmark
```

Phase 52 compliance for this gate is certified from `@neith/qa` in
`docs/domains/neith/performance-regression-certification.md`.

## License Compliance

Phase 52 also requires verified license compliance for the implemented Neith
release stack. The certification for this gate is generated from `@neith/qa` and
verifies:

- Apache-2.0 declarations on the Phase 52 package manifests
- a repository-root Apache-2.0 `LICENSE` file
- Apache-2.0 inheritance across the Neith Linux Cargo workspace
- known compatible direct npm dependency licenses for `@neith/release` and
  `@neith/qa`

This gate is intentionally narrower than the SBOM criterion that follows it. The
published evidence lives in
`docs/domains/neith/license-compliance-certification.md`.

## Accessibility Compliance

Phase 52's next completion criterion requires WCAG 2.1 AA minimum compliance.
`@neith/release` now covers its web distribution surface with a release-focused
accessibility auditor and accessibility-statement generator in
`src/platform/web.ts`.

The auditor validates:

- skip-link presence
- keyboard-only operability
- visible focus treatment
- AA contrast minimums
- text resize and reduced-motion support
- alt text and form label coverage
- landmark structure, heading order, document language, and live-region usage

This is enforced by automated tests in `tests/platform.spec.ts`.

## Documentation Coverage

Phase 52 also requires documentation coverage above 95%. The package now ships
an explicit documentation hub under `docs/domains/neith/release/` plus an
automated coverage gate in `tests/documentation.spec.ts` that maps every source
file in `src/` to the relevant guide, reference, runbook, or training material.

## Integration Coverage

Phase 52's next quality gate requires integration test coverage above 70%.
`@neith/release` now includes a dedicated multi-module integration suite in
`tests/integration.spec.ts`, exposed through both
`pnpm --filter @neith/release run integration` and
`pnpm nx run @neith/release:integration`.

The suite covers eight critical control-plane scenarios:

| Scenario                             | Scope                                                                                          |
| ------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `pipeline-approval-to-rollout`       | gated release train orchestration from pipeline approval through RC evidence and rollout start |
| `security-hotfix-rollback-train`     | critical advisory triage through hotfix planning and rollback execution                        |
| `linux-repository-signing-delivery`  | Linux packaging, artifact signing, repository registration, and install instructions           |
| `auto-update-download-verification`  | update metadata resolution through verified download completion                                |
| `delta-update-offline-recovery-path` | delta patches coordinated with offline installer fallback artifacts                            |
| `web-accessibility-publication`      | web deployment output with accessibility auditing and statement generation                     |
| `docker-cloud-marketplace-catalog`   | container publication aligned with marketplace and enterprise catalog planning                 |
| `enterprise-license-distribution`    | enterprise deployment automation plus site and volume licensing governance                     |

Phase 52 compliance for this gate is certified from `@neith/qa` in
`docs/domains/neith/integration-test-coverage-certification.md`.

## E2E Coverage

Phase 52's end-to-end quality gate requires E2E coverage above 60%.
`@neith/release` now includes a dedicated public-API control-plane E2E suite in
`tests/e2e.spec.ts`, exposed through both `pnpm --filter @neith/release run e2e`
and `pnpm nx run @neith/release:e2e`.

This suite is intentionally stricter than the integration layer: every E2E
scenario imports from `../src/index.js` only, so the release package is
certified through its supported public contract rather than internal module
paths.

The certified E2E journeys are:

| Scenario                                     | Scope                                                                                         |
| -------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `e2e-stable-release-campaign`                | stable release train approval through rollout start and published download inventory          |
| `e2e-security-patch-recovery-campaign`       | critical advisory handling through hotfix planning, rollback rehearsal, and mandatory updates |
| `e2e-linux-repository-distribution-journey`  | Linux package generation, checksum/signature validation, and repository installation guidance |
| `e2e-consumer-update-recovery-journey`       | update discovery, verified download, delta patch orchestration, and offline recovery fallback |
| `e2e-trial-conversion-journey`               | trial access, extension, paid conversion, and free-tier upsell/pricing lifecycle              |
| `e2e-web-marketplace-publication-journey`    | web deployment, accessibility certification, Docker publication, and cloud marketplace output |
| `e2e-enterprise-procurement-rollout-journey` | enterprise catalog publication, deployment planning, site compliance, and volume licensing    |

Phase 52 compliance for this gate is certified from `@neith/qa` in
`docs/domains/neith/e2e-test-coverage-certification.md`.