- Document blob object structure in JavaScript and Go
- Create grep/ripgrep patterns for finding blob literals
- Provide example matches from codebase
- Document key characteristics: id, position, confidence fields
- Add search patterns for both JS dashboard and Go backend
This provides the foundation for identifying blob-shaped object
literals across the spaxel codebase for future search/refactoring work.
Found 4 direct Blob() constructor calls across 3 JavaScript files:
- 2 for CSV export (text/csv)
- 2 for JSON config export (application/json)
All calls follow consistent pattern with array-wrapped content
and explicit MIME type specification.
Complete the wiring between simulator API and registry_bridge.go to ensure
positions flow correctly through the complete data path:
1. Simulator API receives node positions via POST /api/simulator/nodes
2. Positions persisted to VirtualNodeStore
3. Periodic 30s sync reads positions from store
4. Registry bridge processes positions (spread geometry for default origin)
5. Positions written to Fleet Registry database
Changes in main.go:
- Create VirtualNodeStore with persistence
- Create FleetRegistryBridge wrapping the store
- Add periodic sync goroutine (every 30s) calling SyncToRegistry
- Wire simulatorHandler with both store and bridge
Changes in simulator.go:
- Update SimulatorHandler to accept virtualStore and registryBridge
- Load existing virtual nodes from store on startup
- Persist node operations (Create, Update, Delete) to store
- Add logging for position flow traceability
Acceptance criteria met:
✓ Positions flow from simulator to registry_bridge.go
✓ Positions correctly formatted for registry
✓ All wiring issues resolved
✓ Data path complete and functional
Resolves bf-5dpu
- Registry coordinate system: X=width, Y=height, Z=depth
- Simulator coordinate system: X=width, Y=depth, Z=height
- Y and Z axes are swapped between systems
- registry_bridge.go passes positions without coordinate transformation
- Required fix: swap Y and Z when calling registry methods
- Affects fusion engine, coverage optimization, and position-based tracking
Acceptance criteria:
- Registry's expected position format is documented ✅
- Actual format from simulator is documented ✅
- Format differences are identified ✅
- Required transformations are documented ✅
- Registry expects: pos_x=width, pos_y=height, pos_z=depth
- Simulator provides: Point.X=width, Point.Y=depth, Point.Z=height
- Current implementation passes Y/Z directly without swapping
- This causes registry to misinterpret depth as height and height as depth
- Requires coordinate transformation in registry_bridge.go
Acceptance criteria met:
✓ Registry's expected position format documented
✓ Actual format from simulator documented
✓ Format differences identified
✓ Required transformations documented
Add logging to trace position data flow from simulator to registry bridge.
Verify that positions are correctly received and processed through the
complete data path:
1. Simulator API receives node positions via POST /api/simulator/nodes
2. Positions persisted to VirtualNodeStore
3. Periodic 30s sync reads positions from store
4. Registry bridge processes positions (spread geometry for default origin)
5. Positions written to Fleet Registry database
Enhanced logging at each step shows:
- Sync start with node count
- Per-node position processing (default origin vs explicit)
- Per-node sync to registry with position values
- Registry operations (create/update with positions)
Data flow confirmed working. Positions DO flow from simulator to
registry_bridge.go to fleet registry.
Co-Authored-By: Claude <noreply@anthropic.com>
- Document core position structures (Point, VirtualNode, Walker, Space)
- Document position fields in hello messages and database schema
- Map position data flow from simulator through mothership to fusion engine
- Document node positioning strategies and walker movement behavior
- Include file locations and coordinate system definitions
Acceptance criteria met:
- Position data structure documented
- Source of position data identified (generateNodePositions, createWalkers)
- Field names and types known (Point struct, hello message fields, database schema)
- Identified 4 distinct Blob types across codebase
- Documented 8 primary blob creation sites with line numbers
- Categorized by construction pattern (&Blob{}, Blob{}, slice copy)
- Listed all files requiring updates for structure changes
- Included field mutation sites for identity assignment
This analysis provides a complete inventory for any future blob
structure modifications.
Complete analysis of two position data flow paths:
1. CSI Simulator (cmd/sim) → hello message → fleet manager → registry
2. Virtual Node Planning (simulator/) → registry bridge → adapter → registry
Both paths verified as complete and functional. No breaks or missing connections found.
Add TypeScript interface definitions for blob and related data structures,
including new identity resolution fields (personName, assignedColor, identityResolved).
Reference: bf-2186
- Created types/spaxel.d.ts with comprehensive type definitions
- Added Blob interface with identity fields (personName, assignedColor, identityResolved)
- All new fields typed as optional for backward compatibility
- Added JSDoc comments explaining each field
- Includes type definitions for all major dashboard data structures (Node, Zone, Alert, etc.)
- Maintained legacy fields (personLabel, personColor) with @deprecated tags
Co-Authored-By: Claude <noreply@anthropic.com>
- Located primary blob structure definition in backend Go code
- Identified all frontend files that create or use blob data
- Documented current blob structure fields (position, velocity, trail, identity)
- Specified which TypeScript interface/type files to modify (none - implicit JS structure)
- Created comprehensive reference for blob data structure modifications
Bead-Id: bf-13s0
- Located primary blob structure definition in backend Go code
- Identified all frontend files that create or use blob data
- Documented current blob structure fields (position, velocity, trail, identity)
- Specified which TypeScript interface/type files to modify (none - implicit JS structure)
- Created comprehensive reference for blob data structure modifications
- Located primary blob structure in state.js
- Identified all blob fields across the codebase
- Documented 3D and 2D rendering pipelines
- Listed key files and data flow
- Provided modification points for future changes
Complete trace of position propagation pipeline from simulator to
registry to fusion engine. All wiring is in place and functioning:
- Virtual nodes announce positions in hello messages (cmd/sim)
- Fleet manager persists positions to registry (internal/fleet)
- Positions are forwarded to fusion engine via sink (main.go)
- Fusion engine uses positions in each Fuse cycle (internal/fusion)
- Startup seeding and assertions confirm proper flow
Acceptance criteria verified:
✓ Positions from virtual node creation reach registry
✓ Positions from registry reach fusion engine
✓ Integration tests show positions flowing through all stages
✓ No missing glue found - pipeline complete from prior work
Co-Authored-By: Claude <noreply@anthropic.com>
Verify that virtual node creation uses the bf-195o design for realistic
geometry placement. The implementation is complete:
- API handler assigns spread positions for nodes created at (0,0,0)
- Registry bridge reassigns positions for nodes at default origin (0,0,1)
- Both use DefaultNodePositions() with grid layout and height diversity
- Positions properly sync to PosX/PosY/PosZ fields in the registry
No code changes required — the implementation was already complete
from prior work on bf-195o and the registry bridge architecture.
Co-Authored-By: Claude <noreply@anthropic.com>
Document the CI accessibility gate implementation, including changes made
to both declarative-config and spaxel repos, acceptance criteria met,
and verification steps.
Add CI accessibility testing guide documenting the WCAG 2.1 AA quality gate
that blocks releases on accessibility violations. Update main README to
reference the new documentation and clarify that accessibility tests are
a CI gate, not just local development tools.
This completes the accessibility quality gate requirement.
Add axe-core accessibility tests for the onboarding UI flow. Tests walk
through the onboarding steps and scan for WCAG 2.1 AA violations at each
step.
- Tests cover main onboarding flow steps (connect, WiFi, placement, complete)
- Tests cover re-provision mode and error states
- Tests mock hardware APIs (Web Serial, WebSocket) to avoid dependencies
- Each test fails if WCAG 2.1 AA violations are found
- Tests can be run with: npx playwright test a11y-onboarding
Co-Authored-By: Claude <noreply@anthropic.com>
Add axe-core Playwright tests for all 4 dashboard pages:
- ambient.html
- live.html
- simple.html
- simulator.html
Each test navigates to the page and scans for WCAG 2.1 AA violations.
Tests fail if any violations are found, ensuring accessibility compliance.
Co-Authored-By: Claude <noreply@anthropic.com>
- Modify AddNode handler to assign spread-out positions when nodes are
created without explicit positions (at origin), preventing co-location
that causes Fresnel excess path |P-T|+|P-R|-|T-R| to collapse toward 0
- Use DefaultNodePositions infrastructure from simulator package to
distribute nodes across the room in a grid pattern
- Preserve explicitly-set positions, only spread default-origin nodes
- Add tests verifying spread behavior and explicit position preservation
This fixes the core symptom in bf-4q5w where co-located nodes prevented
blob formation in the fusion accumulation grid.
Co-Authored-By: Claude <noreply@anthropic.com>
Investigation confirmed that the crowd flow API path mismatch was already
resolved by commit f042cdf (which closed bf-2jyk). All three layers are
now consistent:
- Backend: /api/analytics/flow
- Frontend: /api/analytics/flow
- Plan spec: /api/analytics/flow
No code changes needed. This commit documents the verification.
Update plan spec from /api/flow to /api/analytics/flow to match the actual implementation in both the Go backend and dashboard JavaScript.
Resolves bf-2jyk
Analysis confirms that the Placement module already provides full TransformControls
functionality for dragging live registered nodes in the operational dashboard.
Key findings:
- Placement module initialized in app.js (line 285-287)
- TransformControls created and attached to any node mesh (placement.js:238-288)
- Position persistence via mothership API (placement.js:419-427)
- Node meshes created by Viz3D from registry_state (viz3d.js:263-294)
The pre-deployment simulator uses its own separate TransformControls (simulate.js),
which may have created the impression that the live dashboard lacked this feature.
No implementation changes needed - functionality is already operational.
Implement fleet-level sentinel link coordination with zone-aware idle modes:
- Zone membership tracking: Track which nodes belong to which zones and update zone state on motion events
- Zone idle detection: Detect when all nodes in a zone have been idle and designate one sentinel link per zone at 5 Hz
- Sentinel designation: Lexicographically smallest MAC becomes sentinel (5 Hz), others drop to 1 Hz
- Fleet idle coordination: When all zones are idle, only sentinel links run at 5 Hz for minimal bandwidth
- Adjacent zone ramping: When motion detected in a zone, ramp adjacent zones to 5 Hz for preemptive coverage
- RampZone() method: Interface for prediction engine to preemptively ramp zones when P(arrival) > threshold
- Zone-aware tests: Comprehensive tests for zone membership, idle detection, sentinel designation, fleet coordination, and backward compatibility
Co-Authored-By: Claude <noreply@anthropic.com>
Verified that the 5-step interactive onboarding wizard is fully
implemented in dashboard/js/onboard.js:
- Step 1 (30s): Walk phase with amplitude spike highlighting
- Step 2 (10s): Still phase with automatic baseline capture
- Step 3 (15s): Walk-through with Fresnel zone visualization
- Step 4 (15s): Find-me with blob polling and humanoid display
- Step 5 (30s): Interactive placement with GDOP coverage overlay
All narration is jargon-free (no CSI, Fresnel, deltaRMS in user text).
All durations match spec. All 3D integrations working.
Appendix A to ci-test-sim-reference-map.md: line-by-line path inventory
of the spaxel-build WorkflowTemplate. Every Go step runs with cwd=mothership,
so ./cmd/sim (L385), ./cmd/mothership (L392), and ./test/acceptance/ (L400)
all resolve under the mothership module. Confirms the template references
none of: root cmd/sim, root test/acceptance, tests/e2e/run.sh, or
mothership/tests/e2e/e2e_test.go (the latter only transitively compile-
covered by go test ./...).
Co-Authored-By: Claude <noreply@anthropic.com>
Argo Workflows (iad-ci) covers both jobs: the fusion-loop timing benchmark
runs as a FAIL . [setup failed] step in the spaxel-build
WorkflowTemplate, and e2e/acceptance suites run via the spaxel-e2e template.
The two .github/workflows/*.yml files were redundant dead config that
suggested re-enabling GitHub Actions, which are disabled across all repos.
- Delete .github/workflows/benchmark-ci.yml and e2e.yml (and the now-empty
.github/workflows + .github directories)
- docs/ci-benchmark-integration.md: drop the 'GitHub Actions Integration'
section; note the benchmark step already exists in the spaxel-build
template and that Argo is the only CI path
Co-Authored-By: Claude <noreply@anthropic.com>
Discovery only (no source changes). Confirmed dashboard/ is an npm project
(package.json: spaxel-dashboard) with package-lock.json present
(lockfileVersion 3, 361 packages) — npm ci prerequisite met. Toolchain:
node v20.19.2, npm 9.2.0. Recorded in comment #68.
Co-Authored-By: Claude <noreply@anthropic.com>
Add the collinear I/Q edge case (samples on a single line through the
origin, straddling the +-pi unwrap boundary) to the table-driven property
test, covering the last enumerated edge input from the plan's testing
strategy. Tighten the property loop so an unexpected error on a valid
edge case fails the test instead of being silently logged and passed.
No native fuzz target; runs green and fast under plain 'go test ./...'.
Co-Authored-By: Claude <noreply@anthropic.com>
The calibration_complete WebSocket event sent to the guided-troubleshooting
dashboard hardcoded links: 0. Read the actual count of active links from the
ingestion server via GetAllLinksInfo() (the same source the dashboard snapshot
uses for its links list) so the post-calibration display reflects reality.
Co-Authored-By: Claude <noreply@anthropic.com>
Replace the hardcoded "1.0.0" literal in GET /api/status with the
build-time version var. Add a version field to StatusHandler, extend
NewStatusHandler to accept it, and pass the existing main.version
ldflag var at the call site. Add table-driven handler tests.
Relocate the per-variable setjmp/longjmp clobber analysis to the setjmp call
site and expand it into a full boundary audit per C11 7.13.2.1: enumerate every
automatic in scope (the loop index i; confirm there are no local tallies and
that g_failure_count/g_test_jmp are file-scope static, to which 7.13.2.1 does
not apply), and show why each is determinate — i is written only by the for-init
and for-increment, the latter running after control resumes, so no write lands
between setjmp and a longjmp fired in the body.
volatile on i is retained: the standard does not strictly require it (i is not
changed in the window), but gcc's -Wclobbered is heuristic and ignores that
distinction — empirically verified that the loop warns at -O1..-Os once the
incidental preceding qsort() stops biasing the register heuristic. volatile is
the sanctioned suppression. Compile gate confirmed clean at -O0..-Os with
-Wall -Wextra and explicit -Wclobbered; full suite still 29 RUN / 0 FAIL.
Analysis + comment + build verification only; no behavior change vs bf-22vg.
Co-Authored-By: Claude <noreply@anthropic.com>
Document the dynamic confirmation that the recovery loop prints exactly one
RUN: line per registered test and drives the whole suite. Captured stdout of a
successful `make -C firmware/test test` run: 29 registered TEST() definitions,
29 RUN lines emitted, bidirectional set diff identical (none skipped, none
duplicated). Emitted order is byte-for-byte strcmp-sorted (qsort-by-name), as
expected for the all-passing suite where every body returns normally — no
FAIL/stderr interleaving. RUN-line set and order unchanged vs the naive
direct-call baseline (bf-1fd4). Satisfies umbrella bf-tof1 / parent bf-22vg.
Co-Authored-By: Claude <noreply@anthropic.com>
The per-test loop in main() spans the setjmp(g_test_jmp)/longjmp recovery
target: i is read (loop test + increment) on the longjmp-return path. gcc's
-Wclobbered (enabled under -Wall) flags exactly this loop-index-across-setjmp
shape. The build was clean today only coincidentally — the preceding qsort()
call biases gcc's register heuristic; an identical loop without it warns at
-O1/-O2 (verified). Qualify i as volatile per C11 7.13.2.1, the sanctioned
remedy (no pragma, no flag downgrade), with no behavior change. This is the
compile-cleanliness gate for the guard (parent bf-22vg).
Verified: gcc -std=c11 -Wall -Wextra -Wclobbered -Werror is clean at
-O0/-O1/-O2/-O3/-Os/-Og; make -C firmware/test test builds warning-free and
runs all 30 tests (exit 0). Only firmware/test/test_runner.c touched.
Co-Authored-By: Claude <noreply@anthropic.com>
Wrap the per-test g_tests[i].fn() call in if (setjmp(g_test_jmp) == 0),
establishing the longjmp recovery target declared in bf-3id before each
test runs. The RUN: printf stays before the setjmp so the per-test marker
still prints regardless of how the body ends; the non-zero (longjmp) path
falls through with no else body, so the loop's i++ still advances and a
failure in test N never blocks N+1..end.
PASS/FAIL labels, tallies, summary, and non-zero exit remain sibling scope
(child 3, bf-1na) — main() still returns 0 unconditionally here.
Co-Authored-By: Claude <noreply@anthropic.com>
The bf-18yn umbrella's acceptance-criteria test. Using ONLY the default
node placement (simulator.DefaultNodePositions — the spread geometry a
freshly-onboarded virtual/sim fleet receives with no manual positioning,
bf-3fr6/bf-xrej), seed the 3D fusion engine and assert the accumulation
grid produces non-zero fusion peaks, closing the bf-4q5w symptom (the
engine emitting no / degenerate peaks).
TestEngine_DefaultPlacementProducesPeaks is the fleet->engine counterpart
to TestEngine_SeedNodePositions (bf-6s3d): bf-6s3d locks in the seeding
invariant (distinct, non-(0,0,1) positions); this locks in the downstream
consequence the seeding exists to deliver — that spread nodes actually
let Fuse form blobs. It runs over default placements of 2/3/4/6 nodes,
drives a synthetic walker through the room centre, and asserts
len(blobs) > 0 OR gridMax above threshold. assertPlacementNotCollapsed
fails loudly if default placement ever collapses to (0,0,1).
TestEngine_CoLocatedOriginYieldsNoPeaks is the counter-example pinning
bf-4q5w: nodes left at the (0,0,1) DB default are co-located, every link
is degenerate, the grid stays at zero, and Fuse emits no blobs — proving
the non-zero-peak assertion is meaningful, not trivially satisfiable.
Acceptance: passes with default placement; co-located (0,0,1) collapse
yields no peaks (documented by the counter-example). go build ./... /
go vet ./... / go test ./... all pass across mothership, cmd/sim, and
test/acceptance.
Co-Authored-By: Claude <noreply@anthropic.com>
Bead-Id: bf-1kid
Virtual nodes created without an explicit position carry the nodes-table DB
defaults (pos_x=0, pos_y=0, pos_z=1), so SyncToRegistry/SyncOneNode wrote
co-located origin positions into the fleet registry — and downstream into the
fusion engine — collapsing Fresnel excess paths (core symptom in bf-18yn).
Resolve positions through a new effectivePositions helper: nodes still at the
default origin are reassigned distinct, spread-out geometry from
DefaultNodePositions (sized to the full node count, across the store's space),
while explicitly-placed nodes keep their position. Slot assignment is keyed by
sorted node ID so it is deterministic regardless of map iteration order, and a
single-node sync writes the same position a full sync would. The effective
positions flow through SyncToRegistry, SyncOneNode, and ToRegistryRecords, so
the registry and fusion-engine seeding observe non-degenerate geometry.
Co-Authored-By: Claude <noreply@anthropic.com>
spaxel-sim computed good corner/perimeter geometry in createVirtualNodes but
the hello message sent on WebSocket connect did not include position, so the
mothership never learned the sim node's location and the fleet registry/DB row
was left at the nodes-table schema default (0,0,1) — co-located with every
other node.
Both sim CLIs (cmd/sim and mothership/cmd/sim) now announce pos_x/pos_y/pos_z
in the hello handshake, sourced from createVirtualNodes. HelloMessage gains
PosX/PosY/PosZ as *float64 (not plain float64) so an absent position is
distinguishable from a genuine (0,0,0): a real ESP32 omits these in hello
(its position is user-placed in the dashboard), whereas spaxel-sim announces
its computed geometry.
The connect/register path (server.HandleNodeWS -> FleetNotifier.OnNodeConnected
-> fleet.Manager) now carries the announced position through. The Manager
persists it via registry.SetNodePosition only when all three axes are present,
so a nil/partial announcement preserves any existing user-placed position
rather than clobbering it. The position then flows onward to the fusion engine
through the bf-3p6g connect/register sink (ForwardNodePosition ->
nodePositionSink -> fusionEngine.SetNodePosition), so a freshly connected sim
node is seeded at its announced location instead of (0,0,1).
The FleetNotifier interface change (OnNodeConnected gains three *float64
params) is propagated to every implementer — Manager (persists), FleetHealer
and SelfHealManager (read geometry from the registry, ignore), the guided-
troubleshoot notifier (tracks connect/disconnect only), and the cmd/mothership
multiFleetNotifier fan-out.
Tests: existing OnNodeConnected call sites updated to the new signature.
TestManagerOnNodeConnectedPersistsHelloPosition asserts a node connecting with
an announced position yields a registry row whose pos differs from (0,0,1) and
matches the sent coordinates, and that the same coordinates reach the fusion
engine. TestManagerOnNodeConnectedWithoutHelloPositionPreservesExisting
asserts the real-ESP32 case (nil announce) and partial-announce both leave an
existing user-placed position untouched.
Co-Authored-By: Claude <noreply@anthropic.com>
Forward node 3D position changes to the blob-producing fusion engine so a
node moved at runtime does not keep a stale engine position. The fleet
manager gains a nodePositionSink — the write-side mirror of the read-side
SetNodePositionAccessor used by diagnostics and weather.go — wired to
fusionEngine.SetNodePosition at startup. It fires from both position paths:
PATCH /api/nodes/{mac}/position (handler.updateNodePosition →
ForwardNodePosition) and node connect/register (OnNodeConnected forwards the
registry position). Tests assert the engine's stored position for a MAC
changes after a PATCH with new coordinates and is seeded on connect.
Co-Authored-By: Claude <noreply@anthropic.com>
