Skip to content

[P1] Optional WAL mode for session persistence (zero-loss) #22

@se-jo-ma

Description

@se-jo-ma

Problem

Between CLIPS fact assertion and the synchronous persistence write, there is a microsecond window where a crash loses the current request's session state. Per design §4.4 (Weakness 4 v1 mitigation), Nautilus should optionally write fact operations to a local append-only WAL file before asserting facts into CLIPS, then replay the WAL on startup.

Verified: grep -ri 'wal\|write.ahead' nautilus/ returns no relevant code.

Design references

  • design-docs/05-ecosystem-roadmap.md:177-193 — full spec including config example
  • design-docs/05-ecosystem-roadmap.md:425 — v1 roadmap item: "Optional write-ahead log (WAL) mode for zero-loss environments"

Code locations to modify

  • nautilus/config/models.py — add persistence.wal_enabled: bool = False + persistence.wal_path: str config
  • new nautilus/core/wal.py — append-only file writer for fact operations (JSON lines)
  • nautilus/core/broker.py — before _engine.assert_fact(), write to WAL when enabled
  • nautilus/core/broker.py::setup() — replay WAL on startup before deserialization
  • nautilus/cli.pyserve accepts --wal-path / --wal-enabled overrides

Acceptance

  • wal_enabled: true configures local append-only fact-operation log.
  • Replay on startup restores pre-crash session state.
  • Latency overhead measured + documented (~0.5ms per design estimate).
  • Integration test simulates crash mid-request, restart, assert prior session exposure intact.

Priority

P1 — load-bearing for "zero data loss" deployments (compliance / classified environments).

Metadata

Metadata

Assignees

No one assigned

    Labels

    P1High priority: load-bearing v1 gaparea/coreBroker core, CLIPS routing, session stateenhancementNew feature or requestsize/M<2 days: multi-file 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