[v1 readiness][maximus] Rust canonical runtime and JS fallback contract

[JeremyDev87]

[v1 readiness][maximus] Rust canonical runtime and JS fallback contract

Goal

Make the Rust-first runtime and limited JS fallback boundary test-backed and explicit before v1.0.0.

Source of Truth

• Parent epic: [v1 readiness] Maximus release gate epic (no version bump) #114
• Repo: JeremyDev87/maximus
• Parent implementation plan artifact: /Users/pjw/.hermes/thread-workcells/discord/282499436049858561/1508085811139051580/TASKS/v1-ddplan-issues/IMPLEMENTATION_PLAN.md
• Version bump, tag, publish, CI dispatch, branch, commit, and PR creation are out of scope for this issue.

Wiki Context Manifest

• Queries attempted: frontend evidence gates release evidence contract, code is not cheap AI maintenance cost ratio, alex core invariants SSoT No Silent Fallback idempotency, 12-factor agents runtime contract event log release workflow, overeager coding agents task scope destructive action, prompt assets skill issue planning evidence
• Wiki sources read: [wiki: frontend/evidence-gates.md], [wiki: principles/code-is-not-cheap.md], [wiki: principles/alex-core-invariants.md], [wiki: harness-engineering/12-factor-agents-runtime-contract.md], [wiki: harness-engineering/overeager-coding-agents-scope-contract.md], [wiki: harness-engineering/prompt-assets.md], [wiki: raw/2026-05-24-ai-maintenance-cost-ratio-source-map.md]
• Relevant wiki facts: v1 readiness requires artifact/runtime/evidence bundles, not only test-green; release and wrapper flows must preserve SSoT, atomicity, idempotency, and No Silent Fallback; destructive or fix-like commands need task-scope/evidence gates; AI-generated velocity must lower future maintenance cost rather than add broad v1 scope.
• remember-wiki applicability / skip reason: skipped; target repos are JeremyDev87/* personal CLI repos, not Remember/dramancompany repos.
• Non-wiki inference: repo-specific split below is based on live local repo docs/config/workflows and npm registry checks performed before issue creation.

Quality Lens Router Output

• Applicable gate families:
  • evidence-contract: v1 readiness, package install, CLI output, release/publish, and fallback claims need concrete proof.
  • simplicity-deletability: v1 work must prefer contract/evidence gaps over broad new features or nonessential abstractions.
  • tdd-systematic-debugging: false-positive, fallback, exit-code, and packaging regressions should be fixture/test-backed.
• Skipped gates:
  • frontend-design: not-applicable; CLI/runtime/docs work only.
  • vercel-agent-skills: not-applicable; no React/Next/Vercel/mobile surface.
  • deploy-token-safety: limited; no token/deploy mutation in this issue, only release credential evidence requirements.

Evidence Contract

• Required evidence:
  • Candidate SHA/version alignment evidence when a candidate is selected.
  • Repo test evidence plus source CLI smoke.
  • npm pack / packed-install evidence for the user-consumed artifact.
  • Release workflow/check/dist-tag/GitHub Release evidence where release automation is touched.
  • Explicit fallback/unsupported-platform evidence where wrapper/native-runtime selection is touched.
• Evidence not applicable:
  • Browser screenshot/DOM: not-applicable, CLI repos.
  • Production URL: not-applicable, npm/GitHub release surface only.
• Blocking evidence gaps:
  • Final v1 version bump/tag is intentionally out of scope for this issue set.

Owned files / likely touched areas

• bin/maximus.js
• test/wrapper-runtime.test.js
• test/packed-wrapper-fallback.test.js
• docs/runtime-transition.md
• docs/npm-wrapper-runtime.md
• CONTRIBUTING.md

Inspect-only files

• src/**
• crates/**
• README*.md
• package.json

Must not touch

• revive JS as canonical runtime
• remove fallback without separate compatibility decision
• version bump/tag/publish

Implementation steps

1. Inventory wrapper runtime resolution order.
2. Add or update tests for requested runtime vs effective runtime and explicit fallback.
3. Ensure Rust-only flags/config paths do not silently fall back to JS.
4. Update docs if code and docs disagree.

Parallelization note

Can run with M2 if wrapper tests do not overlap.

Dependencies / blocked by

Parent only; should happen before release/docs finalization.

Validation / evidence required

• node --test test/wrapper-runtime.test.js test/packed-wrapper-fallback.test.js
• npm test
• cargo test --workspace

Completion criteria

• Required validation evidence is pasted into the PR body or final issue comment.
• No v1 version bump/tag/publish is performed.
• If any required evidence is unavailable, the issue remains open with the gap classified as Medium/High rather than being marked complete.

[JeremyDev87]

ddalggak plan

Live evidence checked:

• Issue [v1 readiness][maximus] Rust canonical runtime and JS fallback contract #115 is open, labeled chore, assigned to JeremyDev87, with no existing comments.
• There are currently no open PRs in JeremyDev87/maximus.
• bin/maximus.js already prefers repo Rust builds, then platform optional packages, and only then evaluates the frozen JS fallback.
• Existing wrapper tests cover Rust-only flags, config-file blocking, placeholder runtimes, packed fallback, and repo-binary precedence.
• docs/npm-wrapper-runtime.md has a runtime-order wording mismatch: it lists optional dependency lookup before repo binaries, while the live launcher resolves repo binaries first.

Concrete implementation plan:

1. Keep Rust as canonical runtime and keep the JS path as a limited compatibility fallback only.
2. Tighten fallback parsing/tests so unknown/non-legacy commands do not silently enter the JS fallback when Rust runtime is unavailable.
3. Align docs with the live launcher precedence and explicitly document the fail-closed fallback boundary.
4. Validate with the issue-requested gates: node --test test/wrapper-runtime.test.js test/packed-wrapper-fallback.test.js, npm test, and cargo test --workspace.

Out of scope honored: no JS canonical-runtime revival, no fallback removal, no version bump/tag/publish.