Zy improvement plan

Prepared: October 11, 2026

Status: Active roadmap, updated October 14, 2026. The 0.3.0-dev implementation adds gradual contracts, recoverable errors, records/enums, project/test/local-package tooling, IPv6 set operations, and a complete explained network validator. Earlier reliable-core, module, formatting, backend, and editor work remains available. User trials and broader release acceptance remain pending. Progress: See implementation progress. Proposed features below remain proposals unless listed there as implemented.

The new concrete APIs are documented in types/errors, projects, and the standard library. Try the network-validator application. Next gates are real user comparisons, richer collection/schema typing, registry distribution, workspace-wide editor indexing, and a real infrastructure adapter. Use the performance baseline before choosing a VM rewrite.

Product direction

Build a small, dependable language for readable network policies and infrastructure validation. Programmers should express IP/subnet rules directly and produce results that operators, reviewers, and learners can understand.

The first useful product should answer: “Does this network inventory satisfy our rules, and if not, exactly what should change?” Start with local data and repeatable evaluation. Treat AI as an optional integration after the deterministic runtime is dependable.

Keep familiar let, fn, braces, and collection syntax. Reform behavior, standard-library boundaries, tooling, and documentation before introducing more syntax.

Who benefits?

Benefits for other people should come through clearer reports, teachable examples, and easier review. A graphical interface can follow if users need it; it is not a prerequisite for usefulness.

Positioning and alternatives

The niche is a hypothesis to validate. OPA/Rego already evaluates policies over structured data, and CUE supports configuration and validation. These primary sources establish existing alternatives; they do not establish that Zy is better.

Compare Zy with those tools and a conventional Go or Python script on the same three tasks: CIDR ownership, subnet allocation, and inventory validation. Assess setup effort, clarity, diagnostics, determinism, and execution time. Continue investing in the niche if native networking values and familiar imperative syntax provide a meaningful advantage for target users.

Avoid broad infrastructure claims until working workflows support them. Native syntax alone does not replace integrations.

Language decisions

Record accepted choices as numbered decisions in docs/decisions/ when implementation starts. Include alternatives, examples, compatibility impact, and tests.

These are recommendations, not accepted language semantics. Publish compatibility notes for changes to existing programs.

Milestone 1: Reliable core

Priority: P0. All later runtime work depends on this milestone.

1. Fix subnet splitting termination. Prefer a counted algorithm with a maximum result size; reject oversized requests before allocating.
2. Keep integer arithmetic and comparison exact. Define checked overflow, division/modulo, minimum-integer negation, and mixed comparisons.
3. Reject out-of-range literals with a located error and useful hint.
4. Audit loop control, function returns, collection equality, argument counts, and mutation. Turn confirmed defects into regression tests.
5. Fix test output capture: restore streams with cleanup and drain while execution runs, or inject an output writer.
6. Bound allocation-heavy built-ins such as range() and subnet splitting. Test step overflow and cancellation.

Acceptance criteria:

• Splitting /0 into /1 returns exactly 0.0.0.0/1 and 128.0.0.0/1 within a bounded subprocess test.
• 9007199254740993 + 0 remains exact and integer ordering above 2^53 is correct.
• 9223372036854775808 produces an error rather than another integer.
• Every accepted numeric choice has examples and tests, including negative values and boundaries.
• Existing examples remain valid or include migration notes.
• Tests, vet, and builds pass on supported Windows, Linux, and macOS configurations.

Use coverage to locate unexamined code. Require direct tests for risky behavior instead of relying on a total percentage.

Milestone 2: A useful local workflow

Priority: P1. Depends on milestone 1 and error/library design decisions.

Add a small standard library for file reading, JSON decoding/encoding, environment access, and path handling. Keep operations explicit and errors inspectable. Begin with JSON; add YAML only when users demonstrate a need. Document redaction and side effects.

Deliver three complete workflows:

1. Network inventory checker: read an inventory, validate addresses against allowed CIDRs, report each violation with its input location and rule.
2. Subnet planner: accept allocation requirements, detect overlaps or exhaustion, and emit a reviewable plan without applying it.
3. Configuration validator: check required fields, supported values, and address ownership; return nonzero on violations.

Provide JSON output for automation and a concise report for people. Select a report API through working examples before introducing new syntax.

Acceptance criteria: Each workflow has sample input, runnable script, expected output, failure fixture, and clean-checkout instructions. Results are repeatable offline. At least three target users complete a task and explain a reported failure.

Milestone 3: Programmer experience

Implemented subset: Run/check/help/version, conservative formatting, local modules, JSON diagnostics/category codes, VS Code syntax/client preview, language-server diagnostics/formatting, and release archive/checksum tooling. See CLI tooling, language server, and releases. Semantic editor features, deeper runtime separation, full-layout formatting, native release validation, and public distribution remain open.

Priority: P1. Depends on stable semantics and workflow evidence.

• Add CLI help/version and explicit run, check, and fmt commands. Preserve zy file.zy during a documented transition; specify exit codes and output streams.
• Add a deterministic formatter; fmt --check detects changes without writing files.
• Add local imports, exports, and standard-library namespaces. Delay a registry/package manager until local modules are useful.
• Add syntax highlighting, then a language server for diagnostics, hover, and navigation.
• Split the interpreter into tested evaluation, values/environments, networking, collections, and built-in responsibilities.
• Consider cmd/zy/ and internal/ only after deciding whether zy/core is a supported embedding API. Provide a transition for go run . if moving the entry point.
• Publish reproducible binaries/checksums with a versioning and release process.

Acceptance criteria: Clean installations run workflows without Go; format/check commands work in CI; editor diagnostics match CLI locations; imports have resolution and cycle tests.

Milestone 4: Optional real integrations

Priority: P2. Depends on milestones 1–3 and actual user demand.

Introduce a provider interface with an explicit mock implementation and one live provider. Read credentials from environment/configuration, never example source. Add timeouts, bounded retries, cancellation, request-size limits, and structured errors. Test offline with a fake HTTP server and fixtures; make live tests opt-in.

Keep probabilistic AI classification separate from deterministic policy evaluation. Show provider/model identity and cost-relevant request information. Do not silently send files, logs, or inventories to a provider.

Identify quarantine() and trigger_alert() as demos or move them into a demo namespace. Future operational adapters need explicit targets, dry-run output, audit records, and documented failure behavior.

Acceptance criteria: Mock/live modes are unambiguous; provider failures are actionable; offline tests need no credentials; successful live calls return provider data. Do not claim vision support until an image-input workflow exists.

Documentation program

Use docs/README.md as the entry point. Separate current behavior, proposed design, and historical notes.

Add a CI documentation gate: check relative links, execute designated runnable snippets, and compare expected outputs. Label context-dependent fragments. Historical proposals stay in docs/archive/ with a non-authoritative warning.

Branding and root organization

Use the temporary Zy logo in assets/branding/ and preserve its prompt/provisional status. Check small-size readability and light/dark surfaces. Before a public identity launch, obtain feedback and conduct name/logo clearance; neither is completed by this asset.

Keep root entry points: README, license, contribution guide, changelog, Go module, CLI source. Guides belong in docs/, runnable code in examples/, branding in assets/, local binaries in ignored bin/. Preserve historical notes. Keep main.go and core/ in place during this initial cleanup so build commands continue working.

Delivery order and ownership

The maintainer owns priority and compatibility decisions. Contributors can own bounded tasks after agreeing on the relevant design. Validate each milestone before dependent work.

Effort is planning guidance, not a delivery promise. Estimate dates after selecting owners and capacity.

Current delivery and next acceptance steps

Lexical hover/completion/definition, lossless formatter layout, runtime file separation, real VS Code extension-host tests, and a Windows light/dark engineering review are implemented. The native matrix explicitly covers amd64/arm64 on Windows, Linux, and macOS; archive CI executes all six cross-built targets. See implementation progress and Actions for recorded validation.

1. Collect real feedback from three general automation users using the updated trial protocol.
2. Resolve observed setup, error-comprehension, and reuse friction before expanding integrations.
3. Extend editor inference/rename and accessibility review only against concrete tasks.
4. Decide publisher identity, public binary distribution, and signing/notarization after native validation and user feedback.
5. Consider multiline argument syntax and safe long-call wrapping; preserve parse behavior and literal/comment spelling.

Success means users solve a concrete problem with correct, understandable results. Engineering review and automated checks do not substitute for participant evidence.