Files
microfish/docs/engineering-log/2026-08-24-simulation-memory-fallback.md
T
Kunthawat Greethong 8b84378fe1 feat: SaaS foundation for CrowdSight
Elevate MiroFish/CrowdSight from single-container dev to a SaaS foundation:

- Local memory backend (Zep-compatible): memory services/models, local graph
  builder + updater, AgentActivity seam, import-boundary isolation; Zep stays
  default, local is opt-in behind MEMORY_BACKEND. Semantic parity not yet proven.
- Durable product persistence: projects/simulations/reports schema (migration
  0007) + tenant/owner-scoped ProductRepository + dual-write + scoped_project
  read-first + ArtifactStore abstraction; durable JobQueue + worker.py.
- SaaS hardening: durable RateLimiter (wired to login), UsageService (LLM
  accounting), redacted AuditService, idempotency, CORS allowlist, safe API
  errors, single-use PasswordResetService + endpoints (covers invite-pending).
- Exactly 3 roles (super_admin/admin/user) with tenant authz policy.
- Admin UI: GET/POST/PATCH /api/admin/users + GET/PUT /api/admin/settings
  (super-admin only, encrypted/masked); AdminView.vue + SettingsView.vue with
  admin/super-admin route guards, th/en i18n.
- Production deploy topology: multi-stage Dockerfile (frontend build + gunicorn
  wsgi + nginx SPA-proxy + supervisord worker), backend/wsgi.py, gunicorn dep.

Backend 197 passed; frontend 10 tests + build green. ruff unavailable (gap).
No commit of credentials; secrets handled via env/.env.example.
Deferred: Zep semantic A/B parity, object storage cutover, mobile QA, EasyPanel
container build of deploy topology.
2026-08-31 13:05:21 +07:00

54 lines
2.4 KiB
Markdown

# Simulation Memory Fallback Hardening — 2026-08-24
## Scope
Close one local-memory safety gap without changing the migration decision:
- `MEMORY_BACKEND=zep` remains the default compatibility path.
- `MEMORY_BACKEND=local` must use an explicitly injected, request-scoped entity-reader factory.
- Local mode must not silently construct `ZepEntityReader` when the factory is absent.
## TDD evidence
1. Added `test_local_backend_refuses_unscoped_zep_reader_fallback` to
`backend/tests/test_simulation_memory_injection.py`.
2. The test failed against the pre-change fallback behavior.
3. `SimulationManager.create_entity_reader()` now raises the stable internal
sentinel `local_entity_reader_factory_required` in local mode when no
factory is injected.
4. Explicit factory injection remains unchanged.
## Verification
- Local-memory regression slice: **11 passed**.
- Backend full suite: **73 passed**.
- Frontend contract tests: **10 passed**.
- Frontend production build: **PASS**; existing chunk-size/dynamic-import warnings remain.
- Python `compileall`: **PASS**.
- `git diff --check`: **PASS**.
- Target-slice added-lines security scan: **0 findings**.
- Full-diff scan matched two password patterns in test-only fixtures; no production credential was identified by that scan.
- `ruff` is unavailable in the current backend environment; no lint pass is claimed.
## Independent review gate
- Fresh read-only reviewer: `deleg_029828b6`.
- Scope was limited to `SimulationManager.create_entity_reader()` and
`test_local_backend_refuses_unscoped_zep_reader_fallback()`.
- Required five-key verdict: `passed=true`, `security_concerns=[]`,
`logic_errors=[]`.
- Reviewer-reported runtime spy: local mode made **0** Zep constructor calls;
the default path made **1** Zep constructor call.
- Reviewer suggestions are non-blocking: add explicit constructor-spy
regression coverage for the local no-call path and the legacy/default path.
They are deferred to a later test-hardening pass; no production behavior gap
was found in this bounded slice.
- This closes the review gate for this slice only. It is not approval of the
full migration, semantic parity, or production readiness.
## Remaining migration boundary
This is a fail-closed guard, not Zep removal or semantic parity proof. Remaining
work includes complete local consumer cutover, parity fixtures, durable resource
persistence, production workers/object storage, and the full tenant E2E matrix.