Dev

.github/workflows/ci.yml

@@ -40,6 +40,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v6
+      # Open3D's Linux wheel loads the system's EGL and OpenGL libraries even when nothing is drawn
+      - run: sudo apt-get update && sudo apt-get install -y --no-install-recommends libegl1 libgl1 libgomp1
       - run: uvx ruff check . && uvx ruff format --check .
       - run: >-
           uv run --no-project --python 3.12 --with numpy --with scipy --with shapely --with pytest --with httpx
@@ -56,6 +58,6 @@ jobs:
           node-version: 22
           cache: pnpm
       - run: pnpm install --frozen-lockfile
-      - run: pnpm --filter @recall/web exec tsc --noEmit
+      - run: pnpm --filter @recall/web typecheck   # next typegen first: PageProps and LayoutProps are generated
       - run: pnpm --filter @recall/web lint
       - run: pnpm --filter @recall/web build

CLAUDE.md

@@ -154,7 +154,7 @@ Grounding rules (system prompt **and** enforced in code):
 - **Guide** (above) is the lead agent and the only one on the live question path.
 - **Verifier** confirms arrival from one camera frame: SAM 3.1 + geometry decide; **Muse Spark 1.1** (hosted, multimodal) is asked only as a tie-break and may only downgrade to `uncertain`, never confirm.
   It is an API use case, so its memory updates (self-healing) keep the one-writer rule. Reached through the `ArrivalVerifier`
-  port: **in-process by default and in the live demo**; over **A2A** optional (`VERIFIER_TRANSPORT`).
+  port: **in-process** (`VERIFIER_TRANSPORT=inprocess`, the only transport built; A2A for the Verifier is optional and not built).
 - **Home Memory agent** exposes read-only skills to external agents over **A2A**, off by default, never the user's live position.
   Inbound input is structured only (one object name, validated against `resources/agents/find-object.input.schema.json`; free
   text never reaches a model or a tool), then the `PromptScreener` port (**Muse Spark Open** or Glimmer, strict JSON, fails closed).
@@ -172,7 +172,9 @@ models are banned):
    into 3D per frame, then **`cluster_dbscan` per label** merges the sightings, so one mug seen in 30 frames becomes one object with
    one centroid and one confidence.
 4. **2D geometry (Shapely):** floor outline polygon, wall segments and furniture footprints, used for `room.json` and the occupancy grid.
-5. **Later scans:** global registration (FPFH + RANSAC) then ICP into the first scan's frame, with Open3D, never hand-rolled.
+5. **Later scans:** the phone relocalises against the room's saved ARWorldMap (ARKit, not a model), so a rescan's poses are
+   already in the first scan's frame (`aligned_to`); if it doesn't relocalise, memory starts fresh and says so. Point-cloud
+   registration (Open3D FPFH + ICP) is **not built** (ADR-037); never hand-roll it.
    Umeyama stays for ARKit ↔ MapAnything poses.
 
 Result: `room.json` = floor polygon, wall segments, furniture boxes, validated against `schemas/RoomModel.yaml`; written by
@@ -207,7 +209,7 @@ feeds it the ARKit intrinsics, poses and LiDAR depth. Its output is then already
 - If any view has a pose, the first view must too.
 - **Umeyama** similarity transform (ARKit vs MapAnything camera centres) is the **check and fallback**: it measures drift,
   and aligns an images-only run if ARKit inputs are missing.
-- Later scans align to the first with Open3D (global registration, then ICP).
+- Later scans share the first scan's frame through ARWorldMap relocalisation (FPFH + ICP not built, ADR-037).
 
 ## 5. Scan episodes and upload
 
@@ -286,9 +288,9 @@ recall/
 │   │   │   │   └── tools.py        tool registry, validated against resources/tools.json
 │   │   │   ├── adapters/
 │   │   │   │   ├── inbound/http/   FastAPI routers: mapping only, no logic
-│   │   │   │   ├── inbound/a2a/    verifier_server.py, home_memory_server.py
+│   │   │   │   ├── inbound/a2a/    home_memory_server.py
 │   │   │   │   └── outbound/
-│   │   │   │       ├── agents/     verifier_a2a_client.py, verifier_inprocess.py
+│   │   │   │       ├── agents/     verifier_inprocess.py (ArrivalVerifier)
 │   │   │   │       ├── vision/     sam31_meta_api.py, spark_vision_meta_api.py (HTTP only)
 │   │   │   │       ├── safety/     meta_model_screen.py (Muse Spark Open or Glimmer, strict JSON verdict)
 │   │   │   │       ├── llm/        openai_compatible.py (+ baseten_spark_open, glimmer_hosted, lmstudio, meta configs)
@@ -308,7 +310,7 @@ recall/
 │       └── src/recall_pipeline/
 │           ├── domain/             Episode, Frame, Pose, arkit_to_opencv(), align.py (Umeyama check/fallback), room_model.py (planes, Shapely 2D geometry), merge.py (per-label clustering), blur.py
 │           ├── application/        process_episode.py, ports.py (Reconstructor, Segmenter, EpisodeSource, ResultSink)
-│           └── adapters/           mapanything_local.py, mapanything_remote.py, sam31_meta_api.py, sam31_modal.py (optional), open3d_geometry.py (clean-up, segment_plane, DBSCAN, FPFH+ICP), rerun_log.py, storage, api_client.py
+│           └── adapters/           mapanything_local.py, mapanything_remote.py, sam31_meta_api.py, sam31_modal.py (optional), open3d_geometry.py (clean-up, segment_plane, DBSCAN), rerun_log.py, storage, api_client.py
 ├── deploy/
 │   ├── baseten/README.md           Spark Open: hosted endpoint, key only
 │   ├── modal/glimmer/              Glimmer serving (TODO(verify) Modal API); fireworks/ alternative
@@ -321,7 +323,7 @@ recall/
 │   ├── run.py
 │   ├── verifier.yaml               20 arrival frames: 10 right spot, 10 wrong spot
 │   └── results.md                  dated accuracy table
-├── examples/a2a-client/home_robot.py  external agent asking Recall over A2A (Muse Spark)
+├── examples/ros2-robot/            a ROS 2 robot loading Recall's export (GET /homes/{id}/robot-package)
 ├── samples/replay/                 recorded scan + recorded model responses for `make demo` (labelled as recorded)
 └── docs/                           (docs/private/ is gitignored: planning docs, ADRs, progress notes, the key list)
     ├── architecture.md             hexagon diagram + both paths (mermaid)
@@ -346,9 +348,11 @@ recall/
 
 ### Make targets
 
-`setup dev demo live probes rerun test lint lint-imports migrate bundle-spec gen-models gen-swift-client eval`
+`setup dev demo live probes rerun test test-all lint lint-imports migrate bundle-spec gen-models gen-swift-client eval`
 
 - `demo`: replay from `samples/replay/`, no keys, output labelled as recorded. `live`: real Meta model calls with `.env`.
+- `test-all`: every suite (API, pipeline, lint, imports, web, iOS unit + UI) under `caffeinate`; each run's logs and
+  summary go to `data/test-runs/` (gitignored) with a line in `runs.jsonl` and `history.md`. `SUITES="api pipeline"` picks some.
 - `probes`: one small real call per external model or service (Meta Model API, Baseten Spark Open, Muse Voice Transcribe, SAM 3.1,
   R2) that prints what worked and appends the result to `docs/verification.md`; needs `.env`; never run in CI.
 - `rerun EPISODE=<path>`: replay a stored episode into the Rerun viewer (`RERUN=1`); dev only, never needed for tests or `make demo`.
@@ -368,7 +372,7 @@ recall/
 | 1 Scan spike + iPhone Scan | Oct 30 to Nov 1 | Full iPhone Scan feature (plain ARKit episode capture, SpeedCoach, metrics, scan report, upload, professional UI); one room episode with ARKit inputs → plane fitting → `room.json` + 3D objects in metres | Objects within ~20 cm of reality on an ARKit-input run (**go/no-go**). Runs alongside phase 2; about 8 to 11 h of iOS work |
 | 2 Memory + agent | Oct 31 to Nov 1 | Memory, spatial relations, Guide agent (Spark Open) with tools | 30-question eval runs; answers only from tool output |
 | 3 Guidance | Nov 1 to 2 | Find, ask, live ARKit guidance, voice; Watch; **Verifier (in-process)** | Walk to an object with eyes closed; arrival confirmed on camera |
-| 4 Proof | Nov 2 to 3 | Viewer, real output on landing page, eval results, sample scan, `samples/replay/`; **A2A servers + schema validation and Meta-model screening + `home_robot.py` demo** | `make demo` works without GPU or keys; verifier precision ≥ 0.9 on 20 frames |
+| 4 Proof | Nov 2 to 3 | Viewer, real output on landing page, eval results, sample scan, `samples/replay/`; **A2A Home Memory server + schema validation and Meta-model screening + robot export demo** | `make demo` works without GPU or keys; verifier precision ≥ 0.9 on 20 frames |
 | 5 Ship | Nov 3 to 4 | README ("What runs where"), 3-minute video, X post, submission, rehearsal | Submitted before Nov 4 evening Warsaw; tag `submission` |
 
 **Schedule:** phases keep their dates; we work overtime (evenings) to finish each one on time rather than cut scope.

INSTALL.md

@@ -0,0 +1,4 @@
+# Installing Recall
+
+The installation guide lives in [docs/install/README.md](docs/install/README.md): what Recall is, then step by step
+for a person or an AI agent (the website, the no-keys demo, and the live setup with the iPhone and the Watch).

Makefile

@@ -2,10 +2,12 @@
 SHELL := /bin/bash
 API := services/api
 PIPE := services/pipeline
+# where the API listens: the LAN by default so the phone reaches it; BIND=127.0.0.1 when a Cloudflare Tunnel is the only way in
+BIND ?= 0.0.0.0
 WEB := apps/web
 REDOCLY := npx -y @redocly/cli@2.72.1
 
-.PHONY: help setup dev worker robot-export regression viewer live demo record probes diagrams pair rerun test lint lint-imports migrate bundle-spec gen-models gen-swift-client eval
+.PHONY: help setup dev worker robot-export regression viewer public-scan live demo record probes diagrams pair rerun test test-all lint lint-imports migrate bundle-spec gen-models gen-swift-client eval
 
 help:
 	@grep -E '^[a-z-]+:.*?## ' $(MAKEFILE_LIST) | awk -F':.*?## ' '{printf "  %-18s %s\n", $$1, $$2}'
@@ -17,7 +19,7 @@ setup: ## Install Python 3.12 services (uv), the web app (pnpm) and generate the
 	$(MAKE) bundle-spec gen-models migrate
 
 dev: ## Run the API on :8000 (reachable on the LAN), the scan worker and the web app on :3000
-	( cd $(API) && uv run recall-api ) & $(MAKE) worker & ( cd $(WEB) && pnpm dev ) ; wait
+	( cd $(API) && RECALL_BIND_HOST=$(BIND) uv run recall-api ) & $(MAKE) worker & ( cd $(WEB) && pnpm dev ) ; wait
 
 worker: ## The scan job worker (Huey on SQLite) and the warm pipeline (MapAnything kept loaded, freed after 10 min idle)
 	( cd $(PIPE) && uv run recall-pipeline serve ) & ( cd $(API) && uv run huey_consumer recall_api.infra.jobs.huey -w 1 -k thread ) ; wait
@@ -31,8 +33,18 @@ robot-export: ## One room's memory for a robot (Nav2 map, things, furniture): ma
 regression: ## Re-run every processed scan now (no posting; cached SAM answers) and compare with the last run
 	cd $(API) && uv run python -c "from recall_api.infra import jobs, regression; print('\n'.join(regression.run(jobs.settings, jobs.run_pipeline)))"
 
+public-scan: ## The real scan for the public site, geometry only (no photo data): make public-scan [HOME_ID=flat] -> apps/web/public/real-scan/<home>/ (review before committing)
+	@H="$(or $(HOME_ID),flat)"; \
+	case "$$H" in *[!a-z0-9-]*|"") echo "HOME_ID: lower-case letters, digits and hyphens only."; exit 2;; esac; \
+	ID=$$(sqlite3 data/recall.db "SELECT id FROM scans WHERE home_id = '$$H' AND status = 'processed' ORDER BY created_at DESC LIMIT 1" 2>/dev/null); \
+	E=$$(ls -d data/blobs/scans/*_$$ID/episode 2>/dev/null | head -1); \
+	if [ -z "$$ID" ] || [ ! -f "$$E/home_colors.npy" ]; then echo "No processed scan of '$$H' yet."; exit 1; fi; \
+	cd $(PIPE)/scripts && uv run --project .. python export_viewer_scan.py --public "$(CURDIR)/$$E" "$(CURDIR)/$(WEB)/public/real-scan/$$H" && \
+	echo "Review apps/web/public/real-scan/$$H/ (no photos, nothing personal) before committing it."
+
 viewer: ## Export a home's newest processed scan for /homes/<home>/viewer: make viewer [HOME_ID=flat] (gitignored output)
 	@H="$(or $(HOME_ID),flat)"; \
+	case "$$H" in *[!a-z0-9-]*|"") echo "HOME_ID: lower-case letters, digits and hyphens only."; exit 2;; esac; \
 	ID=$$(sqlite3 data/recall.db "SELECT id FROM scans WHERE home_id = '$$H' AND status = 'processed' ORDER BY created_at DESC LIMIT 1" 2>/dev/null); \
 	E=$$(ls -d data/blobs/scans/*_$$ID/episode 2>/dev/null | head -1); \
 	if [ -z "$$ID" ] || [ ! -f "$$E/home_colors.npy" ]; then \
@@ -41,7 +53,7 @@ viewer: ## Export a home's newest processed scan for /homes/<home>/viewer: make
 	echo "Open http://localhost:3000/homes/$$H/viewer"
 
 live: ## The API with real Meta model calls (keys from .env), and the scan worker
-	( cd $(API) && uv run recall-api ) & $(MAKE) worker ; wait
+	( cd $(API) && RECALL_BIND_HOST=$(BIND) uv run recall-api ) & $(MAKE) worker ; wait
 
 demo: ## No keys: the API on a memory built from a recorded real scan; the Guide's replies are replayed (labelled recorded)
 	cd $(API) && uv run python -m recall_api.infra.demo serve $(if $(PORT),--port $(PORT))
@@ -68,6 +80,9 @@ test: ## Unit, integration and contract tests for both services
 	cd $(API) && uv run pytest
 	cd $(PIPE) && uv run pytest
 
+test-all: ## Every suite (API, pipeline, lint, imports, web, iOS unit + UI), logs kept in data/test-runs/ (gitignored): make test-all [SUITES="api pipeline"]
+	python3 scripts/test_all.py
+
 lint: ## ruff for both services, ESLint for the web app
 	cd $(API) && uv run ruff check . && uv run ruff format --check .
 	cd $(PIPE) && uv run ruff check . && uv run ruff format --check .