ROADMAP.md

VibeScript Roadmap and Implementation Checklist

This is the working implementation TODO for upcoming VibeScript releases.

How to use this file:

• Keep release scope realistic and bias toward shipping.
• Move unfinished items forward instead of silently dropping them.
• Link each checklist item to an issue/PR once created.
• Mark items complete only after tests/docs are updated.

Release status legend:

• [ ] not started
• [~] in progress (replace manually while working)
• [x] complete

---

Historical Completed Releases

These releases are already shipped and tagged. Completion dates reflect the corresponding git tag date.

v0.1.0 (completed 2025-12-15)

• Added GitHub Actions CI workflow.
• Added stack traces to runtime errors.
• Expanded baseline stdlib coverage.
• Added optional-parens syntax support.
• Added initial CLI support.
• Fixed package/versioning setup for release tagging.

v0.2.0 (completed 2025-12-15)

• Added GoReleaser-based release automation.
• Added recursion depth limit enforcement.
• Added recursion limit test coverage.

v0.2.1 (completed 2025-12-15)

• Pinned GoReleaser version for stable release builds.

v0.2.2 (completed 2025-12-15)

• Adjusted GoReleaser configuration.

v0.3.0 (completed 2025-12-20)

• Added Number#times.
• Added Duration class modeled after ActiveSupport-style duration semantics.

v0.4.0 (completed 2025-12-21)

• Added duration arithmetic support.
• Improved optional-parens behavior for zero-arg methods.
• Implemented Time class.

v0.4.1 (completed 2025-12-21)

• Renamed Time#strftime to Time#format for Go layout alignment.
• Added Duration and Time documentation.

v0.5.0 (completed 2025-12-26)

• Added first pass of gradual typing.
• Added support for classes.
• Added block arguments in method definitions.
• Added numeric literal underscore separators.
• Expanded complex tests/examples coverage.

v0.5.1 (completed 2026-02-07)

• Expanded test suite breadth.
• Landed performance optimizations and refactors.
• Exported CallBlock() for embedders.

v0.6.0 (completed 2026-02-11)

• Added runtime memory quota enforcement.
• Enforced strict effects for globals and require.
• Isolated Script.Call runtime state per invocation.
• Replaced panicking constructors with error-returning APIs.
• Increased CLI/REPL test coverage and added execution benchmarks.

v0.7.0 (completed 2026-02-12)

• Shipped multi-phase string helper expansion.
• Added regex/byte helper coverage and bang-method parity improvements.

v0.8.0 (completed 2026-02-12)

• Expanded Hash built-ins and hash manipulation support.
• Refreshed hash docs and examples.

v0.9.0 (completed 2026-02-12)

• Expanded Array helper surface and enumerable workflows.

v0.10.0 (completed 2026-02-12)

• Made Time and numeric APIs coherent with documented behavior.

v0.11.0 (completed 2026-02-12)

• Improved parse/runtime error feedback and debugging quality.

v0.12.0 (completed 2026-02-13)

• Hardened require behavior for safer module composition.
• Improved private helper/module boundary behavior.
• Improved circular dependency diagnostics for modules.

v0.13.0 (completed 2026-02-17)

• Enforced capability contracts at runtime boundaries.
• Added contract validation paths for capability args and returns.
• Improved capability isolation and contract binding behavior.

---

v0.14.0 - Capability Foundations (completed 2026-02-18)

Goal: make host integrations first-class and safe enough for production workflows.

Capability Adapters

• Add first-party db capability adapter interface and implementation.
• Add first-party events capability adapter interface and implementation.
• Add first-party ctx capability adapter for request/user/tenant metadata.
• Define naming conventions for adapter method exposure (cap.method).
• Ensure all adapters support context propagation and cancellation.

Contracts and Safety

• Add capability method contracts for all new adapter methods.
• Validate args/kwargs/returns for db adapter methods.
• Validate args/kwargs/returns for events adapter methods.
• Add explicit data-only boundary checks for all capability returns.
• Add contract error messages with actionable call-site context.

Script Surface

• Promote examples/background/ scenarios to fully supported behavior.
• Convert examples/future/iteration.vibe from stretch to supported.
• Add docs for common capability patterns (query + transform + enqueue).
• Add docs for capability failure handling patterns.

Testing and Hardening

• Add unit tests for each capability adapter method.
• Add integration tests for mixed capability calls in one script.
• Add negative tests for type violations and invalid payload shapes.
• Add quota/recursion interaction tests with capability-heavy scripts.
• Add benchmarks for capability call overhead.

v0.14.0 Definition of Done

• All new capabilities documented in docs/integration.md.
• Background/future examples run in CI examples suite.
• No contract bypasses in capability call boundaries.

---

v0.15.0 - Type System v2

Goal: make types expressive enough for real workflows while keeping runtime checks predictable.

Type Features

• Add parametric container types: array<T>, hash<K, V>.
• Add union types beyond nil: A | B.
• Add typed object/hash shape syntax for common payload contracts.
• Add typed block signatures where appropriate.
• Define type display formatting for readable runtime errors.

Type Semantics

• Specify variance/invariance rules for container assignments.
• Specify nullability interactions with unions (T? vs T | nil).
• Define coercion policy (no coercion vs explicit coercion helpers).
• Decide strictness for unknown keyword args under typed signatures.

Runtime and Parser

• Extend parser grammar for generic and union type expressions.
• Extend type resolver and internal type representation.
• Add runtime validators for composite/union types.
• Add contract interop so capability contracts can reuse type validators.

Testing and Docs

• Add parser tests for all new type syntax forms.
• Add runtime tests for nested composite type checks.
• Add regression tests for existing any and nullable behavior.
• Expand docs/typing.md with migration examples.

v0.15.0 Definition of Done

• Existing scripts without annotations remain compatible.
• Type errors include parameter name, expected type, and actual type.
• Capability contract validation can use the same type primitives.

---

v0.16.0 - Control Flow and Error Handling

Goal: improve language ergonomics for complex script logic and recovery behavior.

Control Flow

• Add while loops.
• Add until loops.
• Add loop control keywords: break and next.
• Add case/when expression support (if approved).
• Define behavior for nested loop control and block boundaries.

Error Handling Constructs

• Add structured error handling syntax (begin/rescue/ensure or equivalent).
• Add typed error matching where feasible.
• Define re-raise semantics and stack preservation.
• Ensure runtime errors preserve original position and call frames.

Runtime Behavior

• Ensure new control flow integrates with step quota accounting.
• Ensure new constructs integrate with recursion/memory quotas.
• Validate behavior inside class methods, blocks, and capability callbacks.

Testing and Docs

• Add parser/runtime tests for each new control flow construct.
• Add nested control flow tests for edge cases.
• Add docs updates in docs/control-flow.md and docs/errors.md.
• Add examples under examples/control_flow/ for each new feature.

v0.16.0 Definition of Done

• No regressions in existing if/for/range behavior.
• Structured error handling works with assertions and runtime errors.
• Coverage includes nested/edge control-flow paths.

---

v0.17.0 - Modules and Package Ergonomics

Goal: make multi-file script projects easier to compose and maintain.

Module System

• Add explicit export controls (beyond underscore naming).
• Add import aliasing for module objects.
• Define and enforce module namespace conflict behavior.
• Improve cycle error diagnostics with concise chain rendering.
• Add module cache invalidation policy for long-running hosts.

Security and Isolation

• Tighten module root boundary checks and path normalization.
• Add test coverage for path traversal attempts.
• Add explicit policy hooks for module allow/deny lists.

Developer UX

• Add docs for module project layout best practices.
• Add examples for reusable helper modules and namespaced imports.
• Add migration guide for existing require users.

v0.17.0 Definition of Done

• Module APIs are explicit and predictable.
• Error output for cycle/import failures is actionable.
• Security invariants around module paths are fully tested.

---

v0.18.0 - Standard Library Expansion

Goal: reduce host-side boilerplate for common scripting tasks.

Core Utilities

• Add JSON parse/stringify built-ins.
• Add regex matching/replacement helpers.
• Add UUID/random identifier utilities with deterministic test hooks.
• Add richer date/time parsing helpers for common layouts.
• Add safer numeric conversions and clamp/round helpers.

Collections and Strings

• Expand hash helpers for nested transforms and key remapping.
• Expand array helpers for chunking/windowing and stable group operations.
• Add string helpers for common normalization and templating tasks.

Compatibility and Safety

• Define deterministic behavior for locale-sensitive operations.
• Add quotas/guards around potentially expensive operations.
• Ensure new stdlib functions are capability-safe where required.

Testing and Docs

• Add comprehensive docs pages and examples for each new family.
• Add negative tests for malformed JSON/regex patterns.
• Add benchmark coverage for hot stdlib paths.

v0.18.0 Definition of Done

• New stdlib is documented and example-backed.
• Runtime behavior is deterministic across supported OSes.
• Security/performance guardrails are validated by tests.

---

v0.19.0 - Tooling, Quality, and Performance

Goal: improve day-to-day developer productivity and interpreter robustness.

Tooling

• Add canonical formatter command and CI check.
• Add language server protocol (LSP) prototype (hover, completion, diagnostics).
• Add static analysis command for script-level linting.
• Improve REPL inspection commands (globals/functions/types).

Runtime Quality

• Profile evaluator hotspots and optimize dispatch paths.
• Reduce allocations in common value transformations.
• Improve error rendering for deeply nested call stacks.
• Add fuzz tests for parser and runtime edge cases.

CI and Release Engineering

• Add smoke tests for docs examples to CI.
• Add release checklist automation for changelog/version bumps.
• Add compatibility matrix notes for supported Go versions.

v0.19.0 Definition of Done

• Tooling commands are documented and stable.
• Performance regressions are tracked with benchmarks.
• CI includes example and fuzz coverage gates.

---

v1.0.0 - Stabilization and Public API Commitment

Goal: lock the language and embedding API for long-term support.

Stabilization

• Freeze core syntax and document compatibility guarantees.
• Freeze public Go embedding APIs or publish deprecation policy.
• Publish semantic versioning and compatibility contract.
• Complete migration notes for all pre-1.0 breaking changes.

Documentation and Adoption

• Publish complete language reference.
• Publish host integration cookbook with production patterns.
• Provide starter templates for common embedding scenarios.

Final Readiness

• Zero known P0/P1 correctness bugs.
• CI green across supported platforms and Go versions.
• Release process rehearsed and repeatable.

---

v0.20.0 - Performance and Benchmarking (1.0 Push)

Goal: make performance improvements measurable, repeatable, and protected against regressions.

Runtime Performance

• Profile evaluator hotspots and prioritize top 3 CPU paths by cumulative time.
• Reduce Script.Call overhead for short-running scripts (frame/env setup and teardown).
• Optimize method dispatch and member access fast paths.
• Reduce allocations in common collection transforms (map, select, reduce, chunk, window).
• Optimize typed argument/return validation for nested composite types.

Memory and Allocation Discipline

• Reduce transient allocations in stdlib JSON/Regex/String helper paths.
• Reduce temporary map/array churn in module and capability boundary code paths.
• Add per-benchmark allocation targets (allocs/op) for hot runtime paths.
• Add focused regression tests for high-allocation call patterns.

Benchmark Coverage

• Expand benchmark suite for compile, call, control-flow, and typed-runtime workloads.
• Add capability-heavy benchmarks (db/events/context adapters + contract validation).
• Add module-system benchmarks (require, cache hits, cache misses, cycle paths).
• Add stdlib benchmarks for JSON/Regex/Time/String/Array/Hash hot operations.
• Add representative end-to-end benchmarks using tests/complex/*.vibe workloads.

Benchmark Tooling and CI

• Add a single benchmark runner command/script with stable flags and output format.
• Persist benchmark baselines in versioned artifacts for release comparison.
• Add PR-time benchmark smoke checks with threshold-based alerts.
• Add scheduled full benchmark runs with trend reporting.
• Document benchmark interpretation and triage workflow.

Profiling and Diagnostics

• Add reproducible CPU profile capture workflow for compile and runtime benchmarks.
• Add memory profile capture workflow for allocation-heavy scenarios.
• Add flamegraph generation instructions and hotspot triage checklist.
• Add a short "performance playbook" for validating optimizations before merge.

v0.20.0 Definition of Done

• Benchmarks cover runtime, capability, module, and stdlib hot paths.
• CI reports benchmark deltas for guarded smoke benchmarks.
• Measurable improvements are achieved before the v1.0.0 release tag.
• Performance and benchmarking workflows are documented and maintainable.

---

v0.21.0 - Nominal Enums and Type Hardening (completed 2026-03-08)

Goal: add first-class nominal enums and harden the typed runtime around enum resolution and coercion.

Enum Language Support

• Add top-level enum declarations with scoped :: member access.
• Add enum member reflection via .name, .symbol, and .enum.
• Add enum-aware serialization for JSON.stringify and string.template.
• Add typed enum annotations and matching symbol coercion across function and block boundaries.
• Export top-level enums through require alongside module functions.

Resolution and Correctness

• Resolve enum types case-insensitively while rejecting ambiguous matches.
• Preserve enum-named member access and allow enum labels in typed shape fields.
• Reject enum names that shadow built-in types or use reserved suffix forms.
• Fix enum lookup across shadowed envs, nullable types, block owner resolution, and union/hash-key normalization paths.
• Guard recursive normalization against cyclic values.

Tooling and Coverage

• Add runnable enum examples and integration coverage aligned with docs/enums.md.
• Upgrade the REPL to Bubble Tea v2.
• Add race-detector coverage and tighten fuzz/benchmark quality gates.
• Add a just install workflow for the CLI and document editor support integrations.
• Make release workflow reruns idempotent for existing tags.

v0.21.0 Definition of Done

• Enum syntax and typed-runtime behavior are documented and exercised by runnable examples and tests.
• Enum resolution behaves correctly across modules, blocks, shadowed scopes, and typed normalization paths.
• Tooling and release automation changes are documented and stable for the next release cycle.

---

v0.26.2 - Rosetta Port Compatibility Patch (completed 2026-03-08)

Goal: remove a handful of parser and runtime edge cases that were blocking direct ports of Ruby-flavored RosettaCode examples.

Parsing and Control Flow

• Stop if, elsif, while, until, for, return, and raise from accidentally consuming next-line literals and indexing expressions.
• Preserve explicit multiline continuations in line-limited headers for chained calls and operators.
• Support bare return in line-terminated statement form.

Runtime Semantics

• Make && and || evaluate lazily so guard expressions short-circuit correctly.
• Align signed int / int and int % int behavior with floor-style Ruby semantics.
• Add array.length, array.empty?, and array.fetch for lower-friction Ruby ports.
• Reject fractional numeric indices in array.fetch instead of truncating silently.

Coverage and Release Confidence

• Add regression tests for multiline control-flow headers, guard short-circuiting, signed integer arithmetic, and array helper behavior.
• Keep integration expectations aligned with the updated integer arithmetic semantics.

v0.26.2 Definition of Done

• Rosetta-style ports no longer fail on newline-sensitive control-flow parsing, eager boolean guards, or missing array aliases.
• Signed integer arithmetic and array.fetch behavior are covered by targeted regressions and the full go test ./vibes suite.