Programming Language

Nocter

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

Documentation GitHub
/development/docs/v0.4.0.md

Nocter v0.4.0 Release Record

Purpose

v0.4.0 makes a package graph the unit shared by compiler commands and editor analysis. Package structure, dependency requests, and exact dependency locks live in source-level nocter.nct.

The release scope is Phase 0, Phase 1, Phase 2, and the snapshot/package-graph stabilization audit recorded below. Additional feature work is not part of v0.4.0.

Phase 0 Record

v0.4.0 Phase 0: Source-Native Package Roots and Executable Targets completed on 2026-08-05. It removed implicit main.nct, introduced explicit executable targets, public namespace re-exports, and compiler-owned package/module/executable identities. Its provisional use of index.nct as both metadata and module source was intentionally replaced before v0.4.0 release by the Phase 1 package-file contract.

Phase 1 Record

v0.4.0 Phase 1: Deterministic Package Graph completed on 2026-08-05. It established:

  • only a directory containing nocter.nct is a package root
  • nocter.nct contains both a separately modeled manifest and ordinary root-module code
  • index.nct has no package responsibility and remains a directory module
  • an executable requires name; omitted entry selects the root module in nocter.nct, while explicit entry: "." selects the ordinary root directory module in index.nct
  • package-root and path modules have distinct typed identities instead of sharing a sentinel path
  • the legacy source-root concept and entry-file-parent import fallback are absent
  • imports classify module-relative, package-absolute, dependency, and standard-library namespaces without ambient name search
  • #dependencies supports path, Git, and archive sources
  • #lock is deterministic generated data in nocter.nct
  • Git builds use exact commits and archive builds use SHA-256 content identity
  • aliases are package-scoped and physical stores are keyed by PackageId
  • cycles, missing locks, source/lock mismatch, missing caches, path escapes, symlink escapes, and unsafe archive paths are diagnosed
  • nocter fetch, --locked, and --offline have stable behavior
  • CLI compilation follows transitive dependency namespaces
  • LSP discovers nested package ownership, performs no network or manifest writes, and shares locked graph identity for analysis, completion, and navigation
  • formatter and JSON AST preserve the manifest/module boundary

The detailed architecture is in Packages, Dependencies, and Locks.

Non-goals

  • registries, semantic-version ranges, branches as build identity, or a separate lockfile
  • ambient lookup of packages installed in Nocter home
  • dependency deduplication by display name or declared version
  • multi-package workspace membership declarations
  • package-wide incremental invalidation, rename, code actions, or inlay hints
  • test targets or a package test runner

Qualification

Phase 1 passed compiler check, all unit and integration tests, formatter verification, warnings-denied Clippy, public documentation generation, native package and dependency tests, optimized local distribution, installed-home doctor, packaged-home check/build/run, generated native executable execution, and archive inspection. The dependency qualification covers path, Git, and archive inputs; exact offline reuse; graph cycles; cache misses; source/lock mismatch; and failure-atomic generated lock updates.

Phase 2 Record

v0.4.0 Phase 2: Immutable Package-wide LSP Snapshot completed on 2026-08-06. It established:

  • one immutable, generation-numbered snapshot for every normal LSP feature request
  • package graphs loaded once per open package and shared by analysis, navigation, and completion
  • compiler analyses rooted at each open document and retained with their actual source dependencies
  • incremental invalidation of a changed source and its reverse importers while unrelated analyses retain their immutable allocation
  • package-graph revision invalidation when an owning nocter.nct changes
  • read-only open-document overlays for package directives through a locked, offline graph loader
  • separate graph snapshots for nested packages
  • versioned diagnostics and generation-backed semantic-token result identifiers
  • watched disk-file invalidation and consistent diagnostics for independent open documents
  • recovery analyses derived from snapshot documents and graphs without replacing shared state

The detailed architecture is in Immutable LSP Snapshots.

Phase 2 Non-goals

  • scanning every unopened package module to build an ambient symbol index
  • persistent semantic caches, background workers, or concurrent request scheduling
  • rename, code actions, inlay hints, or a package-wide refactoring engine
  • registries, semantic-version selection, or changes to exact dependency identity

Phase 2 Qualification

Phase 2 passes snapshot generation, reverse-import invalidation, unrelated-analysis reuse, unsaved manifest graph replacement, watched-file invalidation, nested-package isolation, independent diagnostic retention, existing LSP behavior, compiler unit tests, formatter verification, and warnings-denied Clippy. It also passes the full repository suite, optimized local distribution, installed-home doctor, and packaged LSP acceptance for versioned diagnostics and semantic-token generation identifiers.

Stabilization Audit Record

The v0.4.0 snapshot and package-graph stabilization audit completed on 2026-08-06. It closed the following correctness gaps without changing package identity or import semantics:

  • frontend loads now return a dependency trace on both success and failure
  • unresolved file and directory-module candidates remain invalidation dependencies, so creating a missing import repairs its open reverse importers
  • logical, canonical, and nearest-existing-ancestor path aliases cover deletion and symlink events
  • package graph loads retain every visited nocter.nct even when a transitive manifest fails
  • invalid manifests discard the current graph instead of exposing a stale successful graph, and a subsequent repair deterministically restores analysis
  • LSP clients can dynamically register **/*.nct watching, and advertised didSave text enters a new immutable generation
  • an explicit server lifecycle rejects pre-initialize, repeated-initialize, and post-shutdown requests with protocol errors
  • a deterministic 49-document workload proves that a shared-source edit rebuilds its 24 reverse importers while retaining all 24 independent analysis allocations

The audit extends the Phase 2 architecture rather than adding a Phase 3 feature surface. Its focused gates cover missing-file creation, malformed-file repair, symlink deletion, malformed root and transitive manifests, dynamic registration responses, saved text, lifecycle ordering, and large-workspace reuse partitions.

Stabilization Qualification

The stabilization audit passes the complete repository verification script: compiler check, 2,204 library tests, all CLI build/run/package/LSP and distributed-home integration tests, corpus tests, formatter verification, and warnings-denied Clippy. Public documentation regeneration, optimized local packaging, installed-home doctor, archive inspection, and packaged-binary JSON-RPC acceptance also pass. The packaged acceptance covers dynamic file-watcher registration, versioned diagnostics, semantic-token generation identifiers, and post-shutdown rejection.

Release Gate

The v0.4.0 release candidate freezes the completed Phase 0 through Phase 2 feature scope. Release qualification requires the complete repository verification suite, public documentation build, optimized distribution build, installed-home doctor, packaged check/build/run and LSP JSON-RPC acceptance, native executable execution, archive inspection, matching 0.4.0 compiler/home/manifest identity, and a clean Git worktree.

Registry and semantic-version selection remain later work because they add resolver policy rather than strengthen the exact-source graph released here.

Qualification Result

The v0.4.0 release gate completed on 2026-08-06. The exact 0.4.0 candidate passed:

  • compiler check and 2,204 library tests
  • 296 CLI build, 7 formatter, 15 LSP protocol, 16 package, 449 native run, 199 distributed-home, and 7 example-corpus integration tests
  • canonical formatting and warnings-denied Clippy
  • generation of all 54 public documentation pages
  • optimized arm64-darwin packaging and installed-home doctor
  • packaged package-mode check, build, run, and generated Mach-O execution
  • packaged JSON-RPC acceptance for saved text, dynamic file watching, versioned diagnostics, generation-backed semantic tokens, and post-shutdown request rejection
  • archive metadata and single-.nocter/-root inspection

The compiler, installed VERSION, distribution manifest, and archive name all identify v0.4.0. No release blocker remains in the frozen Phase 0 through Phase 2 scope.