Add spec ops and config expectations to deployment guide

[yellowman]

Summary

• add spec-derived ops, retention, and backup defaults to the deployment guide
• document configuration management expectations for database-managed knobs versus environment-only secrets

Testing

• python -m compileall liminallm

---

Codex Task

---

Note

Add keyset cursor pagination and metadata to list endpoints, introduce adapter prune recommendations and clustering fixes, and publish a comprehensive deployment guide.

• API & Schemas:
  • Add cursor-based pagination to GET /v1/artifacts, GET /v1/contexts, and GET /v1/contexts/{id}/chunks; responses now include has_next, next_page, next_cursor, and page_size.
  • Update request query params to accept cursor; compute next_cursor via new helpers.
• Storage:
  • Introduce liminallm/storage/cursors.py (encode/decode_*_cursor).
  • Implement keyset pagination and sentinel support in PostgresStore.list_artifacts/list_contexts/list_chunks and MemoryStore.list_artifacts/list_contexts/list_chunks; adjust ordering and bounds; fix max-page sentinel logic; make _safe_float instance-logged.
  • Log connection pool pressure metrics in PostgresStore on slow acquires.
• Clustering/Training:
  • Await warm-start centroid fetch; fix streaming k-means (assignments init, per-cluster learning rate); correct adapter promotion scope/ownership.
  • TrainingWorker: await async store listings; add periodic adapter prune recommendations via ConfigOps; schedule pruning alongside clustering.
• Routes (liminallm/api/routes.py):
  • Wire cursor params and pagination metadata for artifacts/contexts/chunks; compute next_cursor with encode_artifact_cursor/encode_time_id_cursor/encode_index_cursor.
• Docs:
  • Add docs/DEPLOYMENT.md with Docker/manual setup, ops/safety defaults, config management, hybrid scenarios, and troubleshooting.
  • Update README.md to point to deployment guide; revise docs/ISSUES.md audit status and record related fixes/verifications.

^{Written by Cursor Bugbot for commit 673553d. This will update automatically on new commits. Configure here.}

[cursor]

Bug: Timezone mismatch causes cursor pagination to silently fail

The memory store stores naive datetimes (via datetime.utcnow()), but decode_time_id_cursor and decode_artifact_cursor return timezone-aware datetimes (with timezone.utc). Comparing naive and aware datetimes in Python raises TypeError. The comparison at line 1146 (a.created_at < cursor_ts) will fail when a.created_at is naive and cursor_ts is aware. The exception is caught by the except Exception block, which logs a misleading "cursor_decode_failed" message and proceeds without applying cursor filtering, causing pagination to silently return incorrect results. The same issue exists for contexts and chunks pagination in the memory store.

Additional Locations (2)

• liminallm/storage/memory.py#L1567-L1570
• liminallm/storage/memory.py#L1700-L1703

 

[cursor]

Bug: Auto-prune duplicate detection checks wrong field, fails silently

The duplicate detection logic for auto-prune recommendations checks patch.meta.get("auto_prune") to find existing patches, but ConfigPatchAudit.meta is never set when creating patches - it remains None. The auto-prune marker exists only in patch.patch["ops"][0]["path"] (the JSON Patch operation targeting /meta/auto_prune), not in the separate meta field. Since isinstance(patch.meta, dict) is always False, existing auto-prune patches are never detected, causing duplicate recommendations to be created for the same adapters on every 6-hour sweep.