PH-DB CI, hosting, containers, and ORM integration plan¶

Status: Active planning (2026-05-26)
Companion: ph-db-battle-plan.md (engine + WPs A–F) · ph-db-lidb-platform.md (phase index) · ph-db-execution-tracker.md (phases 0–3 + WP-A…K status)
Control plane: lidb-migration-control-plane.md

1. Executive summary¶

Current state (verified 2026-05-26)¶

Production agents still default to LI_CONTROL_PLANE_STORE=supabase. Benchmark dashboard rows for tier_db_* must remain unknown until measured lidb vs Postgres ratios exist.

Target state (MVP)¶

A developer or CI runner can:

1. docker compose up (or lis db start on a host with sibling lidb) → migrated registry-min catalog + health JSON.
2. Run li-cursor-agents with LI_CONTROL_PLANE_STORE=lidb + LI_DATA_DIR (or LI_LIDB_URL) and pass engine e2e without LI_LIDB_MOCK=1.
3. PR CI proves: lidb smoke/pytest, lis db-smoke (cross-checkout lidb), optional non-blocking engine e2e.
4. Nightly CI proves: Postgres 15+ service + tier_db_registry compare harness → honest P95 ratio ingest.

2. Architecture diagram¶

flowchart TB
  subgraph agents["Agent runtimes"]
    LCA["li-cursor-agents"]
    BENCH["benchmarks tier_db_registry"]
  end

  subgraph bridge["Integration layer"]
    PYBR["lidb-liorm-bridge.py subprocess"]
    LIQ["liq compile → plans"]
    LIORM["liorm.execute"]
  end

  subgraph lis_host["lis supervisor (PH-DB-3)"]
    CLI["lis db start|migrate|status|stop"]
    PROF["profiles/registry-min.toml"]
    CLI --> PROF
  end

  subgraph engine["lidb native embed"]
    EMB["lidb_embed binary"]
    MIG["migrations/001_registry.sql"]
    HEAP["LI_DATA_DIR /.lidb/catalog.heap"]
    EMB --> MIG
    EMB --> HEAP
  end

  subgraph optional["Optional bench oracle"]
    PG["Postgres 15+ registry-v1.sql"]
  end

  LCA -->|"LI_DATA_DIR, LI_LIDB_REPO"| PYBR
  LCA -.->|"health gate"| CLI
  BENCH -->|"LIDB_ROOT, POSTGRES_URL"| EMB
  BENCH --> PG

  CLI --> LIORM
  LIQ --> LIORM
  PYBR --> LIORM
  LIORM --> EMB

  BENCH -.->|"compare P95 ratio"| PG

Connection modes

3. CI matrix¶

PR vs nightly summary

4. ORM integration layers¶

Who calls what¶

Agent (Node)  →  runLidbBridge()  →  lidb-liorm-bridge.py  →  liorm.execute / embed_engine
lis db start  →  DbSupervisor     →  liq.compile + register_plan  →  embed_engine.EmbeddedSession
benchmarks    →  registry_oltp.py →  lidb_embed subprocess + psycopg (Postgres)

Contract hardening (WP-J): document stable JSON for lis db status, bridge command stdout, and exec-json lidb_embed responses; forbid RawSql in agent profiles; single-writer semantics for LI_DATA_DIR.

5. Hosting model¶

lis hosting commands (target contract)¶

export LI_DATA_DIR="${LI_DATA_DIR:-./.li-data}"
export LI_PROFILE="${LI_PROFILE:-registry-min}"
export LIDB_REPO="${LIDB_REPO:-../lidb}"

lis db start      # migrate + register plans + write .lis/db-state.json
lis db status     # JSON, exit 0 when ready — assertStoreReady() in agents
lis db migrate    # idempotent
lis db stop       # clear supervisor state; keeps heap

Agent env (li-cursor-agents)

6. Container plan¶

Today: zero PH-DB runtime containers. lic images = compiler CI toolchain only.

Wave 1 — Dev compose (WP-H)¶

Goal: one-command local stack for agents + bench dev.

# Sketch — not shipped yet
services:
  lis-db:
    build:
      context: ..
      dockerfile: lis/docker/Dockerfile.supervisor
    environment:
      LI_DATA_DIR: /data
      LI_PROFILE: registry-min
      LIDB_REPO: /opt/lidb
    volumes:
      - li-data:/data
    healthcheck:
      test: ["CMD", "lis", "db", "status"]
  postgres-oracle:
    image: postgres:16-alpine
    profiles: ["bench"]
    environment:
      POSTGRES_DB: registry_bench

Single-image vs sidecar: prefer single image (lis + baked lidb embed) for MVP; sidecar only if embed build times force split.

Wave 2 — CI image (WP-H + WP-G)¶

CI jobs mount no persistent volume; use mktemp data dir per job.

Wave 3 — Deploy profile (optional)¶

Not in MVP: PG wire listener, Kubernetes operators, Supabase replacement in prod.

7. Workpackages¶

Parallel where noted. Builds on ph-db-battle-plan.md WP-A…F.

WP-G — CI cross-repo gate¶

WP-H — Container images¶

WP-I — lis service profile¶

WP-J — ORM contract hardening¶

WP-K — Bench Postgres in CI¶

Parallelism: WP-H + WP-I after WP-B merge; WP-G + WP-K after WP-A; WP-J overlaps WP-G.

8. Dependencies and merge order¶

Reference ph-db-battle-plan.md §4–6:

flowchart LR
  WPA[WP-A engine]
  WPB[WP-B lis db]
  WPE[WP-E agents persist]
  WPC[WP-C bench harness]
  WPG[WP-G CI cross-repo]
  WPH[WP-H containers]
  WPI[WP-I lis service]
  WPJ[WP-J ORM contracts]
  WPK[WP-K Postgres nightly]

  WPA --> WPG
  WPA --> WPK
  WPB --> WPH
  WPB --> WPI
  WPE --> WPG
  WPC --> WPK
  WPA --> WPJ
  WPB --> WPJ

9. Definition of done — CI + ORM + lis hosting + container MVP¶

All must be true:

1. lidb PR CI: smoke + pytest + security (zero critical skips) + optional embed artifact upload.
2. lis PR CI: cross-checkout lidb + db-smoke.sh mandatory on Linux/macOS.
3. li-cursor-agents PR CI: test:e2e:lidb (mock) required; test:e2e:lidb-engine required or continue-on-error with tracked issue — no LI_LIDB_MOCK in engine job.
4. benchmarks PR CI: validate-only unchanged; nightly job with Postgres service produces honest ratio or failed.
5. ORM: liorm.execute + bridge upsert_agent_run / read_liq against same LI_DATA_DIR without mock.
6. lis hosting: documented quickstart; lis db status is the health gate for agents.
7. Container: published dev image or compose file; README runbook ≤ 10 commands from clone to agent e2e.
8. Honesty: dashboard tier_db_* not green without WP-K measurements; production default store remains supabase until human flip.

10. Anti-goals¶

• No fake-green bench manifests in PR CI (keep validate-only stub).
• No default LI_CONTROL_PLANE_STORE=lidb in production without §9 complete.
• No sqlite3 oracle or embed_engine.py sqlite fallback (PH-DB-3.1).
• No full Postgres wire compatibility or replication in container MVP.
• No replacing lic-ci toolchain images with a monolithic “everything” image before embed CI is stable.
• No TCP loopback requirement for registry-min (embed stays default).
• No claiming lip registry v2 ships on lidb before PH-DB-4 (see battle plan).

References¶