Skip to content

[P1] CLIPS working memory serialization/deserialization for crash recovery #23

@se-jo-ma

Description

@se-jo-ma

Problem

FathomRouter.route() (nautilus/core/fathom_router.py:132) rebuilds CLIPS engine state from clear_facts() + asserts on every request. There is no snapshot/restore of working memory. On crash, all in-memory CLIPS state (cumulative exposure facts, relationship facts, multi-request rule state) is lost — only what was flushed to the audit log survives.

Design references

  • design-docs/05-ecosystem-roadmap.md:423 — v1 roadmap item: "Working memory serialization/deserialization"
  • design-docs/05-ecosystem-roadmap.md:433 — related v1: "Health check endpoint (readiness gating on deserialization)"

Code locations to modify

  • nautilus/core/fathom_router.py — add snapshot() returning serialized fact set + restore(snapshot) for replay
  • nautilus/core/broker.py::setup() — restore from persistence on startup before serving traffic
  • nautilus/core/broker.py — periodic snapshot write (configurable cadence)
  • /readyz endpoint should fail-closed until restore completes
  • Schema for snapshot storage: extend session_pg.py or separate table

Acceptance

  • Snapshot captures complete CLIPS fact set including session exposure multi-slots.
  • Restore reconstructs identical fact set; rule evaluation deterministic before vs after.
  • /readyz returns 503 during restore.
  • Integration test: assert facts, snapshot, restart, restore, assert facts identical.

Priority

P1 — listed as v1 hardening item, unimplemented. Complements WAL (#22) — WAL covers in-flight requests, snapshot covers steady state.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P1High priority: load-bearing v1 gaparea/coreBroker core, CLIPS routing, session stateenhancementNew feature or requestsize/L<1 week: cross-cutting feature

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions