# WRNexusJS quality, migration, and usability roadmap

This page is the authoritative implementation tracker for the repository-wide 0.8 audit. A
point is complete only when its acceptance criteria are executable in CI. Security and release
correctness take priority over new surface area.

## Release blockers

| Status   | Area                | Work                                                                      | Acceptance criteria                                                                |
| -------- | ------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Complete | Dependencies        | Remove high-severity `brace-expansion` and `fast-uri` advisories          | Root `bun audit` and editor `npm audit` report no high/critical findings           |
| Complete | Component showcase  | Use the current `payload` output contract in generated examples and tests | Showcase generation and tests pass without a diff                                  |
| Complete | Formatting          | Normalize the package-kit audit and migration changes                     | `bun run format:check` passes                                                      |
| Complete | Examples            | Resolve every runtime warning, including unregistered `theme-toggle`      | Example tests fail on unexpected framework warnings                                |
| Complete | Application updates | Modernize all `.wrn` files during the 0.8 CLI update                      | Migration is backed up, idempotent, reports unresolved work, and has focused tests |

## Repository delivery and configuration

| Status   | Work                                                                                                                     | Acceptance criteria                                                                                |
| -------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| Complete | Add Linux and Windows CI for install, typecheck, lint, format, packages, examples, services, editor, audits, and staging | Required checks run on every pull request                                                          |
| Complete | Split generators from validators                                                                                         | Every `check:*` and `validate:*` command is read-only; `generate:*` owns writes                    |
| Complete | Add root `LICENSE`, `SECURITY.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, and code of conduct                                | Release validation requires each document                                                          |
| Complete | Normalize all staged package manifests from one schema                                                                   | Description, license, repository, exports, files, engines, side effects, and scripts are validated |
| Complete | Replace `latest` dependency ranges with controlled versions                                                              | Frozen-lockfile installs are reproducible                                                          |
| Complete | Test staged tarballs outside workspace aliases                                                                           | Bun consumer, CLI binary, browser imports, assets, and declarations work from packed artifacts     |
| Complete | Correct publishing documentation and package counts                                                                      | Generated documentation matches the package inventory                                              |

## Framework and package work

Delivered compiler/editor foundation:

- `@wrnexus/syntax` owns the typed canonical formatter API and publishable formatter subpath.
- The compiler, CLI updater, and VS Code extension consume the same implementation.
- The tracked editor compiler bundle has a read-only freshness gate.
- Formatter tests cover structured declarations, markup, comments, parsing, and idempotence.
- Compiler diagnostics are structured for CLI/editor/toolbar consumers, the dev
  pipeline exposes incremental hit/miss/error/timing metrics, and
  `wrnexus doctor --fix` applies conservative idempotent project repairs.

Delivered observability/operations foundation:

- Strict W3C `traceparent` propagation and correlated request/span identifiers.
- One request tracer shared with downstream framework spans and safe exporter failure isolation.
- OTLP/HTTP JSON trace and metric exporters with service resource attributes.
- Redacting structured JSON logs with correlated child loggers.
- Separate liveness and dependency readiness handlers backed by `HealthRegistry`.
- Production runtime `/healthz` and `/readyz` integration with configuration validation.

Delivered public API foundation:

- Every package root and declared subpath is resolved through the TypeScript
  checker into a reviewed `0.8` export baseline.
- CI and production validation reject accidental export removals/renames.
- Intentional API evolution uses a separate generator command and the policy in
  `docs/PUBLIC-API-POLICY.md`.
- Browser payload budgets cover reactive, navigation, and realtime runtimes.
- SSR/store hydration compatibility tests enforce bounded safe JSON, secret
  redaction, script-breakout protection, and escaped CSP nonce attributes.

| Packages                                                               | Planned outcomes                                                                                                                                                                                               |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `core`, `reactive`, `router`, `ssr`, `csr`, `store`, `realtime`        | Stable public API policy; conditional exports; hydration/serialization compatibility; cancellation and disconnect tests; typed routes; one realtime contract; runtime-size budgets                             |
| `syntax`, `compiler`, `typecheck`, `dev-server`, `dev-toolbar`, editor | Shared formatter/compiler artifact; incremental cache metrics; structured diagnostics; fuzz and snapshot tests; code actions; rename/references; `doctor --fix`                                                |
| `auth`, `authz`, `captcha`, `jwt`, `oauth`, `encryption`, `security`   | WebAuthn/OIDC conformance; JWKS rotation; replay/rate-limit tests; built-app header checks; threat models; stable audit events and support matrix                                                              |
| `db`, `cache`, `queue`, `pubsub`, `observability`, `tracking`          | Live database/Redis matrices; cancellation and pool lifecycle; migration locks/dry-run/rollback; distributed invalidation; DLQ/idempotency; OpenTelemetry; health primitives                                   |
| `validation`, `i18n`, `image`, `uploader`, `ui`, `styles`, `helpers`   | JSON Schema/OpenAPI; localized validation; locale extraction/pseudo-locales/RTL; image build optimization; resumable uploads; accessibility and visual regression; typed theme tokens; strict helper ownership |
| `ai`                                                                   | Provider capabilities; structured output; tools; cancellation/retries; usage cost; redaction; deterministic test provider; circuit breakers                                                                    |
| `mobile`, `native`                                                     | Generated Expo/Capacitor E2E builds; typed permissions; deep links; push; offline and secure storage; platform fallbacks                                                                                       |
| `cli`, `plugin`, `test`, `benchmark`                                   | JSON/non-interactive commands; stable error codes; clean scaffold-to-production test; plugin compatibility; consumer test kit; tarball and benchmark budgets                                                   |

Queue/pub-sub reliability delivered in 0.8: bounded queue capacity,
idempotency keys, priorities, delayed/repeated jobs, exponential retries,
inspectable/retryable dead letters, AbortSignal cancellation, graceful/forced
shutdown, durable-store leases, bounded Redis offline writes, reconnect backoff,
subscription replay, awaited in-memory delivery, and idempotent pub/sub close.

Database deployment safety delivered in 0.8: idempotent close that drains active
queries/transactions, registry-wide all-settled pool shutdown, portable
cross-process migration locks with stale-lock recovery, dry-run planning,
between-migration cancellation, and lock-protected rollback.

Cache coherence delivered in 0.8: bounded tag-aware memory caching,
stampede-safe request deduplication, invalidation-safe in-flight loaders, and a
namespaced pub/sub bridge for cross-instance tag, key, and full-cache
invalidation with explicit failure and unsubscribe lifecycle.

AI reliability delivered in 0.8: explicit provider capability discovery,
validated structured output and tool execution, normalized token/cost usage,
abort-aware bounded retries, provider fallback and circuit breakers, metadata-only
attempt telemetry, and a deterministic offline provider for tests and examples.

Mobile portability delivered in 0.8: tested Capacitor and Expo generators, portable
WRN-to-Expo compilation, typed capability permissions, normalized deep-link and push
contracts, pluggable secure-storage and offline stores, and explicit SSR/browser/native
fallback behavior.

Security protocol hardening delivered in 0.8: bounded HTTPS RS256 JWKS caching
with immediate `kid` rotation refresh, strict OIDC discovery and ID-token claim
validation, stable authentication audit-event vocabulary, built production
response header assertions, and a framework/application responsibility matrix
in `docs/SECURITY-SUPPORT-MATRIX.md`.

Validation/localization interoperability delivered in 0.8: JSON Schema 2020-12
and OpenAPI request-body generation, shared localized validation descriptors,
static translation-key extraction, reference-locale missing/extra audits, and
placeholder-safe LTR/RTL pseudo-locales.

Asset and upload delivery delivered in 0.8: bounded deterministic AVIF/WebP/etc.
image build variants through optional Sharp or a custom processor, plus
checksum-verified resumable uploads with out-of-order/idempotent chunks,
expiry/cancel/prune, pluggable durable session state, and single final assembly.

## CLI update contract

The `0.8.0-02-current-wrn-source` migration applies one consistent upgrade point to every WRN
page, layout, component, and store beneath `app/`:

1. Create a complete pre-update backup under `.wrnexus/update-backups/`.
2. Convert legacy events, `$emit`, `event.detail`, function runtimes, dynamic attributes, and
   inline prop declarations to the current syntax.
3. Convert string layouts to imported layout symbols.
4. Add deterministic imports for uniquely resolved application and UI components.
5. Normalize line endings, trailing whitespace, final newlines, and safe structural formatting.
6. Preserve ambiguous source and list it in
   `.wrnexus/migrations/0.8.0-source-modernization.json` for manual review.
7. Run the application formatter, health checks, tests, and production build before committing
   the new framework version marker.

The migration must remain idempotent: running it twice produces byte-identical application
source on the second run.

## Definition of done

A roadmap item may move to **Complete** only with tests, documentation, no high/critical audit
findings, no unexpected warnings, clean formatting, a clean generated-file check, and a staged
package consumer test where publishing behavior changes.
