m2-market/docs/runbook.md

m2-market operational runbook

Catalog rebuild (constitution II rebuildability)

The live memory-api is store/search only — no delete, no partition drop — so m2-market-indexer reindex is an idempotent fill of the current partition, not a rebuild. A true rebuild (needed after listing updates/delists or index corruption) is a fresh-partition switch:

# 1. Fill a fresh partition from the registry (source of truth)
MEMORY_API_PARTITION=market:catalog-v2 \
MEMORY_API_URL=... MEMORY_API_KEY=... FORGEJO_URL=... FORGEJO_TOKEN=... \
LISTING_SCHEMA_PATH=$REPO/schemas/listing.schema.json \
  python3 -m m2_market_indexer.reindex

# 2. Switch every reader (CLI/Store/Scout) by config — no code change
export M2_MARKET_CATALOG_PARTITION=market:catalog-v2   # or config management

# 3. The old partition is abandoned in place (memory-api cannot delete it);
#    it costs storage only. Fold the suffix rotation back when memory-api
#    grows delete support (fedlearn T13 follow-up).

Verification: m2-market search <known listing> returns the same results against the new partition (quickstart.md Scenario E).

memory-api endpoint discovery

The live memory-api container IP changes across Coolify redeploys (known split-brain, two stacks). Resolve the current one:

MC=$(docker ps --format '{{.Names}}' | grep memory-api | head -1)
docker inspect $MC | jq -r '.[0].NetworkSettings.Networks | to_entries[0].value.IPAddress'

Public route: https://memory.machinemachine.ai. Writes need X-API-Key (the key lives in the memory-api container env as MEMORY_API_KEY); reads are currently open.

Ledger

• Public: https://ledger.machinemachine.ai (Cloudflare TLS → Traefik http router — the domain is registered http:// in Coolify on purpose; re-adding https:// recreates the redirect loop).
• Deploy: push to m2/m2-market master → Forgejo webhook (hook id 14) → Coolify deploy. Webhook delivery can lag ~40 s. Manual: GET /api/v1/deploy?uuid=<app> on Coolify.
• Keys: /home/m2/.m2-ledger-keys (host, 0600). Service key reads/installs; admin key grants/snapshots.
• Daily snapshot: host cron 03:10 → POST /snapshot → commits m2/market-registry:audit/YYYY-MM-DD.json. Balance disputes: recompute from the tx log (GET /tx), which is append-only truth.
• Refund semantics: compensating refunds may overdraw a seller (debt position, settled at manual payout reconciliation) — data-model.md §Transaction.

Publish/status flow (known gap, analyze finding I2)

m2-market publish opens the PR with status: "draft"; nothing flips it on merge yet. Until automated: after merging a listing PR, commit status: "published" on main (the indexer only indexes published listings).