CAT Node process lifecycle: ensure host ContentStore, start / stop Flask, and status.
CLI: uv run python -m cats.node {start|stop|status|ensure} (default: start).
Make targets wrap the same commands.
Ownership rule: Node is a client of InfraStructure’s long-lived content-store facet.
Host Kubo is optional operator tooling (ContentStore.ensure); new content lives on
Node CAS-over-HTTP (GET /ldp/cas/<hex>). start soft-probes ContentStore
(Kubo optional for CAS-only Orders); ensure heals/starts Kubo if you want it; stop kills
Flask only — never host Kubo.
make node-start / python -m cats.node start is the standing Flask peer. The Executor image is the one-shot path: python -m cats.executor.once loads one Order, runs Factory → Executor.execute with apply_structure false and a --structure-handoff map, signs the BOM, prints the response, and exits. It does not reconcile Structure. The peer still does. It does not bind Flask. Function and Structure come from the Order; they are not baked into the image (Dockerfile at the repo root). The Job result is CAT_RESULT_DIR (outside CATS_HOME); the peer index under CATS_HOME is the standing Node only.
| Goal | Make | Equivalent CLI |
|---|---|---|
| Bring node online (common path) | make node-up |
ensure, then start |
| Tear down Flask + host Kubo | make node-down |
stop, then ipfs shutdown (Make-only) |
| Heal / start host Kubo only | make content-store-ensure |
uv run python -m cats.node ensure |
| Bind Flask (soft ContentStore probe; Kubo optional) | make node-start |
uv run python -m cats.node start |
| Flask listen + ContentStore ready | make node-status |
uv run python -m cats.node status |
| Stop Flask only | make node-stop |
uv run python -m cats.node stop |
# from repo root
make node-up # content-store-ensure && node-start
make node-status # flask=up|down + content_store=ready|not_ready
make node-stop # Flask only — host Kubo left running
make node-down # node-stop then ipfs shutdown (full local teardown)make node-up is a Make-only convenience that runs content-store-ensure then node-start.
python -m cats.node start soft-probes ContentStore and binds Flask even when Kubo is down.
| Target / CLI | Role |
|---|---|
make content-store-ensure / uv run python -m cats.node ensure |
Operator mutate: repo-tree ContentStore.ensure (heal/start host Kubo) |
make node-start / uv run python -m cats.node start |
Client soft probe: bind Flask; warn if ContentStore API is down; does not heal Kubo |
make node-up |
Convenience: ensure, then start |
make node-down |
Convenience: node-stop then ipfs shutdown (Make-only; not in cats.node) |
Why keep them separate
- AQ ownership: InfraStructure / the operator heal optional host Kubo tooling; the Node client soft-probes and does not own Kubo lifecycle.
- Ops flexibility: Skip ensure for CAS-only Orders (default). Use
node-upwhen you also want Kubo tooling online. Usenode-stopwhen Kubo should keep running; usenode-downfor full local teardown.
Details: STORAGE.md. Content-store phases and heal behavior: IPFS.md.
Optional operator tooling. Live Orders use Node CAS and do not require Kubo.
node-start soft-warns when Kubo is not ready; it does not fail.
make content-store-ensure
# or: uv run python -m cats.node ensure
# or: uv run python data/input/structure/infrastructure/content_store_utils.py ensure- Heals stale
~/.ipfs/repo.lockwhen the API is down but a lock is held, then starts Kubo. - Does not start Flask, kind, Ray, MinIO, or Docker transport.
- Exit
0when ready; non-zero on failure.
make node-start
# or: uv run python -m cats.node start- Soft-probes bootstrap ContentStore, then binds Flask (does not hard-require Kubo).
- Clears a prior
cats.nodelistener on the Node port (does not kill unrelated processes, e.g. AirPlay on 5000). - Fails loud if the port is still held by a non-
cats.nodeprocess — setCAT_NODE_PORT(e.g.5002) when macOS AirPlay owns:5000. - On SIGINT / SIGTERM, exits without stopping host Kubo.
- Serves Order entry at
POST /cat/node/init, Phase 2a LDP control plane, registry, and CAS-over-HTTP data plane (Solid dual-write is separate — seeSOLID.md; registry:BomRegistry.md; storage:STORAGE.md):GET /ldp/boms/— Basic Container listing published BOM URIsGET /ldp/boms/<content_id>— signed ExecutionBom JSON-LD (publish viaRuntime.executeonly; HTTP PUT → 405)GET /ldp/registry/— BOM registry container (Node-local index)GET /ldp/registry/boms/<content_id>— registry record JSON (project_record; no*_cid); PUT → 405GET /ldp/registry/by-data/<data>—{content_id, bom_ids: [...]}GET /ldp/registry/by-order/<order>—{content_id, bom_ids: [...]}GET /ldp/registry/by-content/<digest>— CAS locator map{ content_id, locators }GET /ldp/cas/<digest>— raw CAS blob bytes (sha256 identity); PUT → 405GET /ldp/invoices/<id>— Invoice JSON (Phase 2b URI address); PUT → 405GET /ldp/orders/<id>— Order JSON (Phase 2b URI address); PUT → 405POST /cat/node/init— body may useorder_uri, orbom_uri/bom_ldp_uri/bom_solid_uri/ uniquecontent_id/data_uri/hl(values may behl:/ni:/ http) via the registry (legacyorder_cid/bom_cid/data_cid→ 400; ambiguous → 409{bom_ids}). SetCAT_NODE_HOSTto a peer-reachable address (or rely on Solidbom_solid_uriinhl:hints);127.0.0.1is not mesh-usable.
make node-status
# or: uv run python -m cats.node statusPrints:
flask=up|down
content_store=ready|not_ready
Exit 0 only when Flask is listening and ContentStore is ready; otherwise 1.
Content-store-only status (API up/down, no Flask check):
uv run python data/input/structure/infrastructure/content_store_utils.py statusmake node-stop
# or: uv run python -m cats.node stopStops the Flask Node process only. Host Kubo stays up on purpose when you started it (optional operator tooling outlives Structure destroy and Node exit).
make node-down
# equivalent: make node-stop && ipfs shutdownMake-only convenience: runs node-stop, then ipfs shutdown. Does not live in python -m cats.node stop — the Node CLI remains a ContentStore client and must not shut down host Kubo. Prefer node-stop when Kubo should keep running for the next session; use node-down when you intend to tear down the local daemon too. ipfs shutdown is best-effort (ignored if the API is already down).
INSTALL.md/ENV.md— clone,uv sync, environmentDEMO.md— mesh demo after the Node is upTEST.md— integration tests that need a live NodeBomRegistry.md— Node-local BOM query index (GET /ldp/registry/…)STORAGE.md— content-store vs scratch ownership; why ensure ≠ startIPFS.md— optional host Kubo facet, two-phase ensure (no Docker peers)DASHBOARDS.md— Ray / MinIO / IPFS WebUI once Structure is deployed