Proposal 0002: 0.5 Stable Promotion

• Status: Accepted
• Accepted: 2026-10-14
• Accepted by: David Iach, project lead
• Authors: Codex (AI-assisted draft for maintainer review)
• Created: 2026-10-14
• Discussion: https://github.com/davidiach/geno-lang/issues/177
• Supersedes: None
• Amends: Proposal 0001, Rollout And Observability, prerelease-only publication restriction and the independent-review evidence requirement for this promotion

Summary

Permit a non-prerelease v0.5.0 only after the frozen 0.5 release candidate meets the acceptance criteria below. This is an accepted, narrow amendment to proposal 0001's instruction to publish only as a v0.5 prerelease. Its language, compatibility, security, migration, and technical evidence requirements remain in force; the one-time review exception is recorded below.

The feature baseline is the published v0.5.0-rc.1, commit e0606a6aea1d8da63b539a7eacc47bf49d4f0654. This proposal introduces no language, runtime, API, tooling, or supported-target features. The project-lead decision below authorizes stable publication only after all technical checks pass. Stable promotion requires the recorded authorization and complete technical release evidence described here.

Motivation

RC.1 is published on GitHub and PyPI, with green release checks and installed-package smoke results. The remaining decision is when that same feature set is eligible for stable publication. Proposal 0001 deliberately reserved that decision for a later proposal; passing RC checks alone does not remove its prerelease restriction.

Explicit promotion gates require actionable reports to be resolved and prevent release preparation from becoming another feature cycle. The draft proposed an observation period; the project lead waived that wait for this promotion in the decision below.

Guide-Level Design

Users can evaluate geno-lang==0.5.0rc1 now. When the release gates pass, geno-lang==0.5.0 becomes the non-prerelease package and v0.5.0 the corresponding GitHub release. No additional opt-in flag or new execution mode is introduced.

"Stable" here identifies a non-prerelease version within Geno's existing pre-1.0 compatibility policy. Geno remains a preview project with the component readiness levels in MATURITY.md. This does not grant the separate serious-beta qualification, change package maturity classifiers, or assert organizational production readiness. The current maintainer and support limitations stay visible.

Reference Design

The precise amendment

This accepted proposal amends proposal 0001's Rollout And Observability item 3 to mean:

Publish v0.5 prereleases with curated breaking-change notes. Publish v0.5.0 as a non-prerelease only after the accepted 0.5 Stable Promotion proposal's candidate acceptance and final publication gates are satisfied. After that qualified 0.5.0 publication, permit non-prerelease 0.5.x maintenance releases under the same frozen contract, compatibility policy, and release runbook.

The observation and promotion checklist here governs the first stable 0.5.0. Subsequent 0.5.x patches use the existing runbook's reviewed, fully gated rollback/hotfix process without needing a new stable-promotion proposal or this first-release observation period. This does not authorize features or contract changes in a patch, or waive any existing patch-release check.

All other technical provisions of proposal 0001 remain effective. Its independent-review evidence requirement is subject to the one-time decision below. This record is accepted and permanently numbered; the separate implementation PR updates the rollout cross-reference and release metadata.

Frozen scope

The RC.1 source commit above is the comparison baseline. Every subsequent candidate and the final stable commit must have a reviewed diff against it. Allowed changes are limited to:

• Minimal fixes for demonstrated regressions, security defects, or failures of the documented RC contract, with a reproducer and affected regression tests.
• Corrections to migration instructions, release notes, and evidence.
• Acceptance/numbering of this proposal and the version, changelog, and package metadata changes strictly necessary to publish the approved release.

New syntax, builtins, APIs, CLI switches, templates, targets, expanded compatibility promises, and unrelated refactors or optimization work are deferred. In particular, default isolated-run capability selection #68, alternate entrypoints #80, an agent template #67, performance expansion #51, and new external-corpus CI integration #81 are not added to 0.5.0. Existing external-corpus validation still runs.

No test, security boundary, coverage floor, conformance expectation, performance budget, or validation baseline may be weakened to obtain a passing release. If a necessary fix requires a new feature or a contract change, stop promotion and seek a separately reviewed design; do not widen this freeze implicitly.

Recorded acceptance and one-time exception

On 2026-10-14, project lead David Iach accepted this proposal and directed:

Skip the waiting period and external review. Merge the proposal and release 0.5.0 once all technical checks pass.

For this initial 0.5.0 promotion only, this records a project-lead exception to the public proposal-review window, proposed candidate observation period, and independent external human technical, migration, and release review requirements. No elapsed observation period or external human approval is claimed. This exception also covers proposal 0001's independent-review evidence item and the second-engineer release review in the runbook.

Codex may merge this accepted proposal after its applicable checks pass, and execute publication under this conditional authorization after all remaining technical requirements below pass. Record the exact final SHA and passing evidence against this authorization; it does not claim that the project lead personally inspected that later SHA.

David Iach is the release and incident/support owner. Codex performs execution and automated advisory review under his direction; no additional human reviewer or backup operator is claimed. Evidence must identify actual review providers, commands, results, artifact hashes, and operational owners.

This exception does not waive the frozen scope, security and compatibility requirements, candidate qualification, migration validation, external dogfood, or final publication checks. Ordinary review requirements remain unchanged for future proposals and maintenance releases.

Backend And Target Parity

The supported-target matrix remains unchanged. Candidate evidence must cover the existing interpreter, isolated CLI, unsafe CLI, JSON CLI, generated Python, Node script, directly executed Node ESM, browser, and hosted boundaries as applicable under proposal 0001. It must establish:

• main() -> Unit exits 0; main() -> Int returns 2 as status 2, 258 as status 2, and -1 as status 255 on process-based executable targets.
• Output printed before return is preserved. A normal nonzero integer result adds neither an implicit => N line nor a traceback/runtime diagnostic.
• JSON retains the raw result, including exact large integers, with normalized process status and empty diagnostics for a normal integer return. A genuine runtime error still fails with a diagnostic.
• Embedding returns the raw value and leaves the caller running. Importing generated Python or Node ESM is inert. Browser behavior retains its existing display semantics without a process status or new Node dependencies.
• Existing async/aliased entrypoint and non-Unit/Int behavior remains covered by the retained tests and conformance cases. Hosted capability denials remain fail-closed.

Existing focused tests, all-backend conformance, and installed-distribution smokes provide this evidence; no new backend or public contract is introduced.

Compatibility And Migration

Promotion itself introduces no additional source, runtime, diagnostic, API, package-format, or artifact-format break relative to the accepted candidate. The 0.4-to-0.5 changes still require the complete migration notes already published with RC.1 and the 0.5 specification.

In particular, an integer returned by main now controls process status instead of being displayed as => N. A caller that wants a displayed result should print it and return Unit. Shell set -e and subprocess check=True users must account for intentional nonzero exits, including valid JSON responses. Embedding continues to receive the raw return value. The release notes must also retain the RC's stricter type/import validation and async migration notes, plus the documented capability, entrypoint, and experimental-tooling limits.

The v0.4 conformance corpus stays frozen; the v0.5 specification and corpus remain the accepted compatibility contract. A regression fix may add a case that enforces that contract, but may not rewrite old expectations to hide a behavior change.

Security And Resource Limits

Promotion does not alter capabilities, process isolation, cooperative timeouts, memory/step/response limits, host callbacks, or generated-code trust boundaries. geno.run() and JSON mode retain their documented in-process limitations; generated JavaScript continues to require a trusted execution environment.

Any new open sandbox or capability finding blocks promotion under the release runbook, regardless of the soak time or other green checks. Dependency audits and locked installs must pass without suppressing findings to ship. Record a release owner and incident/support owner with the access needed to respond, and identify the actual technical review provider. The recorded decision above waives the second external human review for this promotion only.

Testing And Validation

Candidate acceptance checklist

All criteria below must be evidenced before preparing the final stable tag. The release evidence must include URLs or retained logs, exact commits and artifact hashes, environments, commands, outcomes, actual review results, and the recorded project-lead authorization.

• Identified candidate: record the immutable RC tag, source SHA, wheel and sdist SHA-256 hashes, publication times, and reviewed delta from RC.1. Verify GitHub and PyPI distribute the tested artifact bytes.
• Observation period: waived. The project-lead decision above waives the proposed seven-day (168-hour) observation period for this promotion. Record actual publication times; do not report an observation period as completed.
• Triage complete: review all RC feedback and open issues affecting the frozen contract at candidate qualification, and refresh triage before publication. No unresolved wrong result, backend/exit-contract mismatch, supported-platform install failure, crash, data loss, security boundary defect, or required-gate failure remains. Document the rationale, owner, and user-visible limitation for any deferred report; an enhancement request outside the frozen scope is not by itself a blocker. Untriaged reports of these failures block promotion.
• Existing automated gates: the candidate passes the canonical local release gate, hosted Python 3.10-3.13 and supported OS matrix, security suite and bounty corpus, dependency audits, all retained conformance with Node required, and the existing Scheduled Quality performance/deep-fuzz jobs. Record the tested source SHA for each run. Keep the 80% coverage minimum, existing performance budgets, and expected conditional skips explicit.
• Installed-package behavior: fresh wheel and sdist installs pass scripts/smoke_installed_geno.py, scripts/smoke_clean_install.py, and the exit/output/JSON/embedding/import cases above, denied-capability and genuine-runtime-error cases, and the runbook's post-release checks. Use the published candidate artifacts, not an editable source checkout, and record Python and Node versions and platforms.
• External dogfood: against that same published candidate, run all 101 applications in geno-corpus at 977644bbc4a7ca3b0210cf8f024d9c9c67be2b42 through their existing test, run, and Python-compile checks. Run the six clean/broken CLI and compiled Python/ Node cases for geno-sitecheck at 767c435cd1e2ac864b5e8e92980b317669f524a1, retaining the minimal migration patch and checking exact output, status 0/2, and empty error output. Record the driver commands, pinned sources, any patches, environment, artifact hash, and logs so another reviewer can reproduce the runs.
• Migration validation: inspect the installed-package and dogfood evidence and record whether the migration guidance matches the observed behavior, with any technical objections resolved. Identify the actual automated review provider; external human review is waived. This is not a claim of a minimum user count or of broad production adoption.
• Release handoff: named release, review, and incident/support owners confirm the final checklist, known limitations, support route, and rollback plan. Link this accepted proposal, the lead decision, and actual technical review evidence.

Use the established commands and workflows; this proposal adds no new CI system. The release runbook, Makefile, and local CI guide remain the command references:

make release-check
make security
make dependency-audit
python3 scripts/run_conformance.py --all-retained --target all --require-node

The release wrapper python3 scripts/local_ci.py release is also supported. The existing Scheduled Quality workflow supplies performance and deep-fuzz evidence. A passing PR check is not a substitute for the complete release gate.

Evidence available at draft creation

These are RC.1 baseline results, not completed stable-promotion approvals:

The published RC.1 wheel SHA-256 is 6a4d6fbfbeddf8f4cb8f4c6021e540ae80476c622bbaea91f90ca042f58580ff; the sdist SHA-256 is 879689e613763dbf3e7b75ae2ca5b05e0e6cdf8f0b043c94e6ea057d3adf0840. The release's checksum manifest and publication workflow are the evidence sources; version strings alone do not establish artifact identity.

Rollout And Observability

1. Record acceptance. The project-lead decision above accepts proposal 0002 and waives waiting and external human review for this promotion. Merge this accepted design record after its technical checks pass. Acceptance does not itself mark the RC technical gates complete.
2. Qualify the final RC. Any code, dependency, build, executable-behavior, security, or package-content fix requires a new RC tag and version, fresh affected validation, and full release gates. Do not replace RC.1's tag or artifacts. The elapsed observation requirement is waived; technical qualification is not. Repository-only editorial/evidence corrections that cannot change installed bytes or behavior may retain the existing candidate; record the diff and why that exception applies. Test corrections to migration or contract guidance against the installed RC before its checklist item can pass.
3. Prepare a separate stable implementation PR. Only after candidate acceptance, change the aligned version metadata to 0.5.0, finalize the changelog/migration notes, and link the accepted proposal and evidence. Every runtime or packaging fix must already have shipped in the qualified RC; the stable diff may contain only reviewed release metadata and docs. Verify alignment with python3 scripts/check_version_alignment.py. Review the complete RC.1-to-final diff, including any intervening main changes; do not absorb unrelated work merely because it merged to main.
4. Validate the exact final commit. Require green main and hosted supported-platform CI, a fresh canonical local release gate and security/dependency/quality checks on the final stable SHA. Record that exact SHA and its passing evidence under the lead's conditional decision above before pushing a tag. The reviewed version/docs-only promotion delta in step 3 does not itself require another RC; any other change returns to step 2. RC.1 results do not replace this final-version validation.
5. Publish and verify. After the preceding gates and recorded authorization, push the v0.5.0 tag to trigger the existing publishing workflow. That workflow must pass its tag/version/main checks and canonical gate, build wheel and sdist once, and pass strict Twine validation and installed-artifact smokes before uploading those same tested bytes to PyPI as 0.5.0. After the workflow succeeds, publish the non-prerelease GitHub release with those artifacts, curated migration notes, known limitations, source SHA, checksums, and evidence links. Verify public GitHub/PyPI hashes and repeat fresh public-install and runbook smokes. Publication is not considered complete until they pass.
6. Respond to regressions. The named incident owner triages reports. A failed post-publication smoke stops promotion announcements and triggers the runbook's revert/forward-fix process and a newly versioned, fully gated patch release as appropriate. Never rewrite public history, move a released tag, or replace uploaded artifacts. Keep the RC release and evidence intact.

There is no promised stable publication date. Publication is eligible only after all retained technical criteria pass and the evidence is recorded. The waived waiting and external-review requirements are not technical passes.

Alternatives

• Continue prereleases indefinitely: preserves proposal 0001 as written, but supplies no reviewable decision for stable promotion.
• Promote immediately because PR CI is green: omits the retained full release, installed-artifact, migration, external-dogfood, and final-SHA gates.
• Expand 0.5.0 to close all open enhancements: breaks the freeze and changes the candidate being evaluated. Defer those enhancements to later work.
• Require serious-beta qualification for this version number: conflates a non-prerelease tag with a separate organizational/product readiness claim. Keep that qualification, including its staffing and longer evidence gates, independent and do not claim it for this release.

Unresolved Questions

The promotion decision, waiting exception, external-review exception, and release/support ownership are recorded above. Technical qualification must still determine whether any blocker requires a regression fix and RC.2. Resolve all blocker reports before choosing the final candidate.

Rendered from docs/proposals/0002-0.5-stable-promotion.md in the Geno repository.