nWave Framework v4.2.0

Coming from 3.x? nWave 4 is a major release and a breaking change from 3.x. The old delivery runtime is removed, the 3.x delivery commands are replaced by the nwdes verbs, and Python 3.11 or newer is required. There is no converter for 3.x roadmaps or execution logs. Read the migration guide before you upgrade: https://github.com/nWave-ai/nWave/blob/main/docs/guides/migrating-from-3x.md.

nWave 4.2.0 is a feature release for 4.1.0. The nwdes design close now asks
for two more decisions, a crafter may commit more of a lane, and the close of an
acceptance oracle checks that it covers the design. A close that an earlier
version accepted can now be refused.

What changed

• Acceptance rows bind design obligations by key. Each design law and each
  architectural or contract test that a slice owes is one obligation key. The
  author bundle lists every owed key. A key the slice owns is listed with its
  case text. A shared key is listed by its id alone, and its text stays in the
  architecture brief. A Tested row binds keys with --obligation. A close that
  leaves an owed key unbound refuses with OpenObligation, one block per open
  key, and says how to record the missing row. Covers of a law or a
  test are refused by name, so a design law is bound through its key.
• A broad law needs a generative test that exists. When a Tested row binds
  a law with a broad domain, the test it cites must have the form path::name,
  and the name must occur as a whole word in a readable file under the
  repository root. If it does not, the close refuses with UnresolvedTest.
• The run list of each slice is computed. The commands that verify a slice
  are now computed from the architectural and contract tests of the design, so
  no record repeats them and none can be missing. A test command whose program
  cannot be found still refuses the design close.
• An examine probe runs the verbs that need a slice. A review of an oracle
  or of a slice can be run through the probe. --slice stays refused for a
  verb that does not take it, in both its spellings.
• A reopened review round starts clean. nwdes review open --from-current
  keeps the findings of the earlier round and starts with no observations,
  because each observation is bound to the commit that recorded it. Before,
  the reviewer had to remove them by hand, one id at a time.
• The tools read their policy once. One invocation reads its policy file
  once, and the role grammar is built once per process.
• The design close asks for an agreement decision and a prefactoring
  decision. The design needs an agreement row, or a reasoned
  not-applicable. An agreement row names one party to a shared contract that the
  change touches, Producer or Consumer, and says if it was migrated, is
  unchanged and compatible, or is incompatible. Each slice with a code target
  also needs one prefactoring decision: the refactor that makes the change
  easier, the existing oracle that keeps the behavior, and the command that
  checks it, or a reasoned not-applicable. A close without them refuses with
  MissingFact.
• A crafter may commit any file of its lane, except protected ones. Before,
  a crafter could commit only the declared targets of its slices, so a file the
  slice needed was refused. Now the default is every changed lane file. The
  protected files stay refused with ProtectedFile: an oracle or support file
  that the oracle review has not approved, and every feature record except the
  crafter's own run record. A crafter may also refactor on its own, at levels L1
  to L4, in the code of its slice. The instructions tell it to commit each
  refactor alone and green with --type refactor, before the behavior change.
• The architect owns the model files that a law cites. The architect also
  owns the formal/ folder of the feature. Another role that changes one of
  them is refused with UnownedFile and the name of the architect; a crafter is
  refused with ProtectedFile.
• An oracle review no longer stops for the oracles of other slices. The
  oracle and support files of slices that are not under review are not dirty
  evidence any more, so three oracles drafted in one lane can be reviewed
  together. Dirty production code still refuses.

Upgrade

• Upgrade the nwave-ai package with the Python package manager that
  installed it, then rerun nwave-ai install --platform <host> for your host.
• Records made by an earlier version still open and read. An acceptance row
  that is already stored and that covers a design law or test by its id keeps
  binding it while the row is unchanged. When you edit such a row, or add a
  new one, bind the keys with --obligation. A design close for a slice that
  owes a test must have a command for that test; the run list is now computed,
  so remove any list you copied by hand.
• A design that you close again needs the new decisions first. Record the
  agreement with nwdes design agreement add, and the prefactoring of each code
  slice with nwdes design prefactoring set --in SLICE. Where one does not
  apply, use nwdes design not-applicable add --analysis agreement or
  --analysis prefactoring with a reason.

nWave Framework v4.2.0

Release Date: 2026-11-05

Promoted from: v4.2.0rc1

Full Changelog: v4.1.0...v4.2.0

Installation

uv (recommended):

uv tool install nwave-ai

pipx (fallback):

pipx install nwave-ai

Breaking Changes

0 changes

Features

58 changes

Bug Fixes

18 changes

Other Changes

156 changes

This repository's history is one commit per release, so individual changes are not listed here; the breaking changes are listed in the highlights above.

Migration decision SHA-256: 010a58a5f989bba5d80ab58bb16dbf3133bc3fa64f4ed8f142947c89a9bb312a