docs(openspec): reconstruct the missing connectivity-contracts record

ba6ff1e shipped the connectivity contracts with no OpenSpec cycle, and
77c3970 brought only the baseline specs level with the code. The change
record itself was still absent, so the framework's history showed the
promise without the reasoning, and the archive had no entry for work
that is now in main.

Add the proposal, design, and delta specs the cycle should have produced
before implementation, and archive them. The deltas state exactly what
those two commits landed and are archived with --skip-specs because the
baseline already carries them; the proposal records that the record was
reconstructed after the fact rather than presenting it as a cycle that
ran in order.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: lfagundes

openspec/changes/archive/2026-08-09-connectivity-contracts/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-08

openspec/changes/archive/2026-08-09-connectivity-contracts/design.md

@@ -0,0 +1,79 @@
+## Context
+
+The framework's geometric contracts were complete in one direction only.
+`assertNotIntersecting`, `assertFreeWithin` and `assertNoPairwiseIntersections`
+all answer "are these two things apart?", and a project can build a thorough
+suite out of them without ever asking "is this one thing whole?".
+
+The failure that exposed the gap is cheap to produce and invisible to every
+existing check. A leaf's `render()` returns several solids; a backend "union"
+of solids that do not overlap does not fail, it hands back a compound; the
+resulting mesh is watertight because each shell is closed; `mesh.volume` is
+positive; the STL exports; the viewer draws something part-shaped. Three shop
+projects shipped that way (fan blades 3mm off the hub, a selector fork joined to
+nothing, label bars floating off a plate), and in each case the whole suite was
+green.
+
+Two mechanisms were available and neither was in use: trimesh can split a mesh
+into connected components, and the build already walks the node tree before
+publishing.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Assertions that count connected bodies, including the inverse contract —
+  two features that MUST fuse.
+- A build-time guard for the property, opt-in per node, that refuses to publish
+  a model which arrives in pieces.
+- Zero cost for a project that does not ask for the check.
+
+**Non-Goals:**
+
+- Inferring intent. The framework does not guess that a node "should" be one
+  body; a node says so.
+- Repairing geometry. A violation is reported, never welded automatically.
+- Changing the meaning of watertightness or any existing assertion.
+
+## Decisions
+
+**Count components with `only_watertight=False`.** The question is whether the
+geometry hangs together. Filtering to watertight components would drop exactly
+the evidence being sought, since the fragments in every observed defect were
+themselves closed shells.
+
+**`bodies` defaults to `None`, not to 1.** One is the right contract for almost
+every printed part, but defaulting to it would make every existing project start
+loading meshes at build time and would fail assemblies that are legitimately
+multi-body. The declaration is opt-in; `assertNoDisconnectedParts` applies the
+"one body unless declared otherwise" reading in the test layer instead, where a
+project has chosen to ask.
+
+**`FusionNode` declares `bodies = 1`.** Its docstring already promised "a
+single, inseparable unit". Declaring it turns that promise into something the
+build enforces, and a fusion of non-overlapping children — the exact way a part
+falls apart — now fails instead of publishing.
+
+**Verify on both publication paths.** The natural place looks like STL
+completion, but a build that finds every artifact already current publishes too,
+without rendering anything. Checking only the rendering path would let a
+fragmented model reach the maker on the second build. `_verify_declared_bodies`
+therefore runs immediately before `_write_viewer_snapshot` on both paths, inside
+the existing try/except, so a violation is reported through `errors.json` like
+any other build failure and the previous publication keeps serving.
+
+**`assertJoined` is the inverse of the adjacency rule.** Everywhere else,
+shared volume between two nodes is a defect. Within a single printed part it is
+the requirement, and tangential contact is not enough: solids fuse only where
+they overlap. `min_weld_volume` lets a drawing state how much overlap the
+junction needs, so a weld that exists but is too thin to print fails too.
+
+## Risks / Trade-offs
+
+- `verify_bodies()` reads a node's mesh, which costs a load. Confined to nodes
+  that declare a count, so the cost is opted into.
+- A project that legitimately publishes a multi-body leaf must declare it, or
+  leave it undeclared. This is intended: silence means unchecked, never
+  "must be one".
+- Splitting very large meshes is not free; the check runs once per publication,
+  not per assertion sweep.

openspec/changes/archive/2026-08-09-connectivity-contracts/proposal.md

@@ -0,0 +1,80 @@
+## Why
+
+A rigid printed part is meant to be one connected solid, and nothing in the
+framework could tell whether it was.
+
+Watertightness is a per-shell property. A mesh of several disjoint closed
+shells is watertight, has a positive volume, exports a valid STL, and renders
+in the viewer looking like a part. So a component whose features never actually
+reached each other passes every check the framework offers. Three shop projects
+shipped parts in pieces through that gap — a windmill fan whose four blades stop
+3mm short of their hub (4 bodies), a selector fork whose neck reaches neither
+the ring nor the carriage (2 bodies), a selector gate whose label bars float off
+the plate (14 bodies) — all watertight, all green.
+
+The geometric pressure a project can express was also one-sided. Adjacency
+discipline (`assertNoPairwiseIntersections`) pushes parts apart, and a part that
+has fallen into fragments satisfies every non-interference contract there is.
+Nothing pulled the other way.
+
+## What Changes
+
+- Connectivity assertions over the number of connected solids in a node's
+  world-space mesh: `assertOneBody`, `assertBodyCount`, `assertJoined`
+  (with an optional minimum weld volume — the one case where two features are
+  *required* to share volume), and `assertNoDisconnectedParts` as the tree-wide
+  counterpart of the pairwise adjacency sweep.
+- Components are counted by splitting the mesh without filtering to watertight
+  components, because a fragment that is itself closed is exactly the case
+  worth catching.
+- Nodes MAY declare a `bodies` count. `verify_bodies()` raises
+  `DisconnectedBodyError` naming the node, the declared count and the actual
+  one. The default is `None`, so a project that does not ask for the check
+  never loads its meshes on account of it.
+- `FusionNode` declares `bodies = 1`, making "a single, inseparable unit" a
+  checked property rather than a docstring promise.
+- The builder verifies declared counts before publishing, on both publication
+  paths — including the one that finds the artifact set already current, so a
+  fragmented model cannot reach the maker by that route either. A violation
+  prevents publication and is reported through the ordinary error channel.
+
+## Capabilities
+
+### New Capabilities
+
+None. This adds contracts to the existing test framework, node model, and build
+pipeline.
+
+### Modified Capabilities
+
+- `test-framework`: the connectivity assertions, how bodies are counted, and
+  the statement that watertightness is not evidence of connectedness.
+- `node-model`: the `bodies` declaration, its unchecked default, the
+  `FusionNode` count, and what `verify_bodies()` raises and skips.
+- `build-pipeline`: verification before publication on both publishing paths, a
+  violation reported through the ordinary error channel, and no mesh read for a
+  project that declares nothing.
+
+## Impact
+
+- `solid_node/test.py` — `_body_count` helper and the four assertions.
+- `solid_node/node/base.py` — the `bodies` attribute, `verify_bodies()`, and
+  `DisconnectedBodyError`.
+- `solid_node/node/fusion.py` — `bodies = 1`.
+- `solid_node/core/builder.py` — `_verify_declared_bodies()` called on both
+  publication paths.
+- `tests/test_connectivity.py` — new; `tests/test_builder_lifecycle.py` —
+  extended for the publication paths.
+- Existing projects are unaffected until they declare a count or write a
+  connectivity contract: the default leaves every node unchecked.
+
+## Record note
+
+This record was reconstructed after the fact. The implementation
+(`ba6ff1e`) shipped without an OpenSpec cycle, and the baseline specs were
+brought level with the code in a follow-up (`77c3970`) that still left the
+change record missing. This change directory carries the proposal, design, and
+delta specs the cycle should have produced before implementation; the delta
+specs state exactly what those two commits landed, and are archived with
+`--skip-specs` because the baseline already carries them. Nothing here
+describes an intention that was not implemented.

openspec/changes/archive/2026-08-09-connectivity-contracts/specs/build-pipeline/spec.md

@@ -0,0 +1,31 @@
+## ADDED Requirements
+
+### Requirement: A declared body count is verified before publication
+
+Before publishing, a builder SHALL walk the loaded node tree and hold every
+node that declares a `bodies` count to it. Verification SHALL happen on every
+path that publishes, including the one that finds the artifact set already
+current, so a model that arrives in pieces cannot reach the maker by that
+route either. A violation SHALL prevent publication and SHALL be reported
+through the same error channel as any other build failure, leaving the
+previously published artifacts in place. Nodes that declare no count SHALL be
+skipped without their meshes being read, so the check costs nothing until a
+project asks for it.
+
+#### Scenario: A fragmented model is not published
+
+- **WHEN** a build completes rendering and a node's built mesh has a different
+  number of connected solids than the node declares
+- **THEN** no viewer snapshot is published and the failure is reported through
+  `errors.json`
+
+#### Scenario: The already-current path is checked too
+
+- **WHEN** a builder finds the published artifact set already current for a
+  node that violates its declared body count
+- **THEN** it republishes nothing and reports the failure
+
+#### Scenario: A project that declares nothing pays nothing
+
+- **WHEN** a build runs on a tree in which no node declares a body count
+- **THEN** no mesh is read for this check and publication proceeds as usual

openspec/changes/archive/2026-08-09-connectivity-contracts/specs/node-model/spec.md

@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Declared connected-body count
+
+A node MAY declare, through a class-level `bodies` attribute, how many
+connected solids its own built mesh must have. The default SHALL be `None`,
+leaving the node unchecked so that a project which does not ask for the check
+never loads its meshes on account of it. `FusionNode` SHALL declare
+`bodies = 1`, making "a single, inseparable unit" a checked property rather
+than a docstring promise.
+
+`verify_bodies()` SHALL raise `DisconnectedBodyError`, naming the node, the
+declared count, and the actual one, when a declared count does not match the
+number of connected components of the node's mesh. A node that declares no
+count, and a node that is not rigid, SHALL be skipped without its mesh being
+read.
+
+#### Scenario: A fusion arrives in pieces
+
+- **WHEN** `verify_bodies()` runs on a `FusionNode` whose children do not
+  actually overlap
+- **THEN** it raises `DisconnectedBodyError` naming the node and its body
+  count
+
+#### Scenario: An undeclared node is not checked
+
+- **WHEN** `verify_bodies()` runs on a node that leaves `bodies` at its
+  default
+- **THEN** it returns without reading the node's mesh
+
+#### Scenario: A non-rigid node is not checked
+
+- **WHEN** `verify_bodies()` runs on a non-rigid node that declares a count
+- **THEN** it returns without reading the node's mesh

openspec/changes/archive/2026-08-09-connectivity-contracts/specs/test-framework/spec.md

@@ -0,0 +1,54 @@
+## ADDED Requirements
+
+### Requirement: Connectivity assertions
+
+The system SHALL provide assertions over the number of connected solids in a
+node's world-space mesh, counted by splitting the mesh without filtering to
+watertight components — a fragment that is itself closed still counts as a
+body. Watertightness SHALL NOT be treated as evidence of connectedness: a mesh
+of several disjoint closed shells is watertight, has positive volume, and
+exports a valid STL.
+
+- `assertOneBody(node)` — the node is a single connected solid.
+- `assertBodyCount(node, expected)` — the node has exactly `expected`
+  connected components; the failure names the node, the expected count, and
+  the actual one.
+- `assertJoined(node1, node2, min_weld_volume=0.0)` — the union of the two
+  nodes' meshes is exactly one connected component, so the two features are
+  genuinely the same printed part. `min_weld_volume` (mm³) additionally
+  requires the volume they share to reach that value. Solids that only touch
+  tangentially SHALL NOT count as joined.
+- `assertNoDisconnectedParts(node)` — the connectivity counterpart of the
+  pairwise adjacency sweep: it walks the assembled tree to its leaves and
+  holds every leaf to the count its `bodies` attribute declares, defaulting
+  to one body when it declares none.
+
+#### Scenario: A part in pieces is caught
+
+- **WHEN** `assertOneBody` runs on a node whose features never reached each
+  other, producing a watertight mesh of several closed shells
+- **THEN** an `AssertionError` names the node and the number of bodies its
+  mesh has
+
+#### Scenario: Tangential contact is not a join
+
+- **WHEN** `assertJoined` runs on two solids that meet exactly on a face
+  without overlapping
+- **THEN** the assertion fails, because their union is still two components
+
+#### Scenario: A weld below the stated minimum
+
+- **WHEN** two features overlap, but by less than `min_weld_volume`
+- **THEN** the assertion fails naming the weld volume and the required one
+
+#### Scenario: Assembly-wide connectivity
+
+- **WHEN** `assertNoDisconnectedParts` sweeps an assembly in which one leaf
+  anywhere in the tree has fallen into fragments
+- **THEN** an `AssertionError` names that leaf
+
+#### Scenario: A leaf that is deliberately several bodies
+
+- **WHEN** a leaf declares `bodies = 2` and its mesh has two components
+- **THEN** the sweep passes for that leaf, and fails it if the mesh has any
+  other number

openspec/changes/archive/2026-08-09-connectivity-contracts/tasks.md

@@ -0,0 +1,52 @@
+## 1. Counting bodies
+
+- [x] 1.1 Red: two disjoint closed shells are watertight and have positive
+      volume — the premise the rest of the change rests on.
+- [x] 1.2 Add `_body_count`, splitting with `only_watertight=False` so a
+      fragment that is itself closed still counts as a body.
+
+## 2. Connectivity assertions
+
+- [x] 2.1 Red: `assertOneBody` fails on a node whose features never reached
+      each other, naming the node and its body count, and passes a single
+      solid.
+- [x] 2.2 Red: `assertBodyCount` names both the expected and the actual count
+      on failure.
+- [x] 2.3 Red: `assertJoined` fails two solids meeting exactly on a face
+      without overlapping, and passes genuinely overlapping features.
+- [x] 2.4 Red: `assertJoined` fails a weld below `min_weld_volume` and passes
+      one above it.
+- [x] 2.5 Red: `assertNoDisconnectedParts` fails when one leaf anywhere in the
+      tree has fragmented, passes an all-single-body tree, respects a leaf that
+      declares a legitimate count, and still enforces that declared count.
+- [x] 2.6 Implement the four assertions in `solid_node/test.py`.
+
+## 3. Declared body counts on nodes
+
+- [x] 3.1 Red: `AbstractBaseNode` declares no count by default and
+      `FusionNode` declares one body.
+- [x] 3.2 Red: `verify_bodies()` passes a single body, raises
+      `DisconnectedBodyError` on a fragmented result, and skips an undeclared
+      node and a non-rigid node without reading their meshes.
+- [x] 3.3 Implement `bodies`, `verify_bodies()` and `DisconnectedBodyError` in
+      `solid_node/node/base.py`, and `bodies = 1` in `solid_node/node/fusion.py`.
+
+## 4. Build-time verification
+
+- [x] 4.1 Red: a build whose node violates its declared count publishes no
+      viewer snapshot and reports through `errors.json`.
+- [x] 4.2 Red: the already-current publication path performs the same check and
+      republishes nothing on violation.
+- [x] 4.3 Implement `_verify_declared_bodies()` and call it before
+      `_write_viewer_snapshot()` on both publication paths.
+- [x] 4.4 Confirm the lifecycle tests exercise the real `verify_bodies`, not a
+      no-op stand-in, so the undeclared-node fast path stays honest.
+
+## 5. Whole-system checks
+
+- [x] 5.1 Run the full framework test suite.
+- [x] 5.2 Verify against the three real defects — the windmill fan, the
+      selector fork, the selector gate — and confirm each goes red with its
+      body count named.
+- [x] 5.3 Sync the baseline specs for `test-framework`, `node-model` and
+      `build-pipeline`.