Programming Language

Nocter

A self-contained systems language built around simplicity, encapsulation, and foolproof design.

Documentation GitHub
/development/milestones/v0.21.0.md

v0.21.0: Standard Map and Set

Status: Phase 0 through Phase 5 complete; published and externally audited (2026-08-30). The publication record freezes the release evidence. v0.20.0 compiler-foundation work is included in this release but did not produce a separate public release.

v0.21.0 returns development to practical APIs. It introduces one ordinary associative choice for normal code: Map<K, V> and Set<T>. A private hash table supplies the first implementation. The public surface does not expose HashMap, HashSet, buckets, probing, a fixed algorithm, or custom hasher selection.

The normative public contract is Associative Collections. This milestone owns work order and completion evidence only; it does not restate that public behavior.

Phase 0: Public Contract and Feasibility

Status: complete and reviewed. The Phase 0 review records the authority, representation, ownership, failure, capability, source, and tooling audit plus qualification evidence.

Phase 0 fixes the names, semantic guarantees, keyed mapping literal, operator surface, hashing coherence, allocation policy, and implementation prerequisites before collection source is added.

Accepted Direction

  • Map and Set are the only standard unordered associative collection names.
  • Hash-table representation remains private and may change without a source-level rename.
  • A future ordered/range-query contract uses TreeMap and TreeSet.
  • Hash requires equality and writes through an opaque algorithm-neutral HashState.
  • Default collections own hidden target-derived seeds; hash output and iteration order are not stable data.
  • Map literals use a declaration-driven keyed argument pack rather than compiler knowledge of Map or an alternating flat argument list.
  • Map indexing is total-by-termination; optional lookup remains get/get_mut, and insertion remains explicit.
  • Map iteration keeps keys readonly, Set has no mutable iteration, and owned iteration transfers every stored owner exactly once.
  • Ordinary allocation failure terminates; explicit try_ APIs use TryAllocator and publish no partial mutation.

Existing Capabilities

The current language and standard library already provide:

  • interface prerequisites, including structural equality consequences of K impl Hash;
  • generic readonly/readwrite indexing operators;
  • readonly, readwrite, and owned expansion with exact-size iterators;
  • current and recoverable allocator ownership with delayed binding;
  • RawBuffer, typed alignment and size, arbitrary-offset store, take, and drop operations;
  • move-only values, sparse-slot cleanup ingredients, and explicit destruction;
  • result/optional composition needed by try_insert returning V?!.

The private table therefore remains ordinary Nocter source. No compiler-owned Map, Set, hash table, bucket, or probing operation is justified.

Required New Capabilities

Only three prerequisites are admitted before table implementation:

  1. 1. Keyed argument packs and mapping literals. Syntax, checking, ownership, cleanup, typed ABI, target lowering, diagnostics, formatter, AST JSON, and editor presentation must carry one key/value entry identity. It may not lower to two unrelated packs or alternating values.
  2. Explicit numeric mixing APIs. The built-in unsigned integer source surface needs the minimum wrapping-add, wrapping-multiply, bitwise-XOR, and rotate operations required by the selected source-defined hash state. Normal arithmetic remains trapping and the operator grammar does not gain collection-driven special cases.
  3. Target entropy boundary. Standard internals need one narrow target operation that fills a seed without exposing OS handles or recoverable I/O policy to public collection constructors. Hashing and table policy remain standard-library source responsibilities.

No additional feature may be added speculatively. In particular, general tuple values, collection-specific compiler lowering, custom hashers, entry handles, and mapping spread are not Phase 0 prerequisites.

Completion Gate

Phase 0 is complete only when:

  • the public specification is the sole authority for Map, Set, Hash, literals, operators, ordering, mutation, allocation, and iteration guarantees;
  • the milestone and handoff identify the exact reusable capabilities and exact missing prerequisites without copying public semantics into compiler architecture documents;
  • every public name is representation-neutral and no HashMap/HashSet alias is retained;
  • mapping literal syntax has one key/value pack model and an unambiguous empty form;
  • duplicate, replacement, cleanup, failed growth, and key-stability behavior is defined;
  • ordered and unordered contracts remain distinct;
  • generated public documentation and link validation pass;
  • review finds no host-language API inference, representation leak, alternate source of truth, compatibility spelling, or unowned implementation prerequisite.

Phase 1: Keyed Packs and Numeric/Entropy Prerequisites

Status: complete and reviewed. The Phase 1 review records the semantic transport, ownership, ABI, target, standard-library, and tooling audit plus qualification evidence.

Implement and qualify the three Phase 0 prerequisites. Keyed packs extend the existing pack model end to end and preserve one semantic entry identity through ABI lowering. Numeric mixing is an ordinary primitive-type API. Entropy is a narrow target boundary behind standard internals.

Phase 1 does not add collection storage.

Phase 2: Hash Foundation

Status: complete and reviewed. The Phase 2 review records the opaque-state boundary, source algorithm, standard implementations, visibility audit, and native qualification evidence.

Create std/hash, its opaque state, source-defined mixing, and coherent implementations for the adopted primitive, text, view, and owning collection types. Verify equal-value consistency, component boundaries, seed separation, no allocation, and no stable output exposure.

Phase 3: Private Table and Map

Status: complete and reviewed. The Phase 3 review records the representation, ownership, failure, visibility, and native qualification audit.

Build one private open-addressed table in ordinary standard-library source, then expose Map over it. Verify collision chains, replacement, removal, growth, sparse cleanup, zero-sized key/value types, move-only values, allocator affinity, failure atomicity, indexing, and equality.

Phase 4: Iteration and Set

Status: complete and reviewed. The Phase 4 review records the cursor boundary, borrowed and owning cleanup, Set delegation, prelude qualification, and native evidence.

Add semantic map entry types, three map iterators, two set iterators, exact remaining lengths, and Set as a thin semantic layer over the same private storage engine. Add prelude exports only after the complete public types qualify.

Phase 5: Practical Qualification

Status: complete and reviewed. The Phase 5 review records runnable native application coverage, public-source diagnostics, shared semantic editor queries, canonical formatting, and the final representation-boundary audit.

Add runnable examples, native integration coverage, diagnostics, hover, completion, signature help, navigation, formatting, and generated documentation. Review the complete standard-library surface and private representation boundary before release preparation.

Release Preparation

The frozen release boundary, candidate identity, and qualification contract are recorded in v0.21.0-release-preparation.md. Qualification and publication remain separate operations: preparing or qualifying the candidate does not tag, upload, or publish an artifact.

The separately authorized publication is recorded in ../releases/v0.21.0.md.