Skip to content

Nexus v2.0 — Constitutional Spine

Choose a tag to compare

View all tags
@STiFLeR7 STiFLeR7 released this 03 Aug 05:15
· 11 commits to master since this release
v2.0.0
c502826

Nexus v2.0

The first complete release of Nexus v2 — the constitutional reasoning spine architecture. An independent, from-scratch rebuild (nexus_*, 31 packages) that does not supersede v1; the two run as separate processes sharing one repository.

Highlights

  • Constitutional AI Control Plane — thirteen single-owner capabilities (Understand → Reason → Ground → Contextualize → Plan → Coordinate → Execute → Act → Observe → Validate → Recover → Reflect → Learn), fused into one deterministic Goal→Knowledge driver, governed throughout by the Policy Engine and Human Interaction.
  • Deterministic execution — every stage is replayable; reasoning is confined to Understand/Reason/Estimation and always emits an immutable recorded decision.
  • Policy-governed autonomy — the Constitutional Scheduler drives one-time, recurring, and delayed goal dispatch under fully-automatic or human-governed AutonomyMode, fronted by the Approval Exchange.
  • Replay & restart — an append-only, event-sourced SQLite/WAL log is the single source of truth; all state is a deterministic projection of that log, enabling exact replay and restart from any interruption point.
  • Runtime abstraction — a provider-agnostic Runtime Adapter contract (Claude, Gemini, Shell shipped) with a discovery/selection layer independent of any concrete provider.
  • Human Interaction — the operator-facing façade over the constitutional pipeline and Approval Exchange.
  • Scheduler — durable, restart-safe autonomous goal dispatch.
  • Operations — a read-only projection plane over the durable event log for observability of every session, runtime, and replay.
  • Documentation — a full architecture portal: ADR audit and traceability, benchmarks and operational evidence, production examples, and a contributor/release governance guide.
  • Examples — 10 runnable, self-contained example scripts covering the full constitutional pipeline, policy governance, runtime selection, memory, scheduling, approval, replay, recovery, and autonomous workflows.
  • Tutorials — 10 companion tutorials walking the same ground step by step, from install through autonomous workflow.
  • Benchmarks — documented guarantees, persistence/replay characteristics, scheduler behavior, and quality gates with operational evidence.

Links

Validation (this release)

  • ruff check: clean
  • ruff format --check: clean (all files touched by this release)
  • mypy --strict: clean — 388 source files across all v2 packages
  • pytest: 2941 passed, 1 skipped (opt-in live-API smoke test), 175 warnings
  • coverage: 97.97% (gate: 95%)
  • uv build (sdist + wheel): succeeds from a clean checkout

Known Limitations

(Reproduced verbatim from CHANGELOG.md's [2.0.0] entry — see there and docs/v2/RC2_EXECUTION_IDENTITY_REPORT.md for full detail.)

  • No v1→v2 data migration tool. The two strata use entirely different persistence models and remain fully isolated. ADR-008-shadow-migration.md documents a designed-but-unbuilt migration path. v2 today only supports a greenfield (empty durable log) start.
  • Durable schema is unversioned. nexus_infra/durable.py uses CREATE TABLE IF NOT EXISTS only — idempotent bootstrap, no migration mechanism. A future schema change has no upgrade path for an existing durable file.
  • ADR-009 (INV-37 runtime-selection ownership) remains unratified — Proposed status, carried forward from RC1.
  • Two frozen-contract candidates remain un-frozen despite meeting the freeze trigger: engineering_strategy and repository_understanding. Their shape can still change without the formal process the other 18 frozen contracts get.
  • nexus_briefings and nexus_operator remain unwired into the running product (real, tested code; zero live callers) — flagged since P17, unchanged.
  • A latent, not-currently-triggered identity-collision shape remains in GraphNode.identifier and its checkpoint reference — safe today only because every consumer looks them up inside an already goal-scoped container; documented in docs/v2/RC2_EXECUTION_IDENTITY_REPORT.md §9 as a fast-follow, not a defect in the current code path.
  • ConstitutionalPipeline.execution_graph()/execution_state() (read-only inspection methods) share the same un-scoped-reconstruction shape RC2 fixed on the restart path — dormant, not fixed, documented as a fast-follow.
  • Recovery is invoked with checkpoint_ref=None unconditionally — an independent INV-18 gap noted during RC2's audit, unrelated to identity, not in RC2's scope.
Assets 2
Loading