WRNexusJS/docs/IMPLEMENTATION-ROADMAP-0.8.md

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.