# OSHUN V1 In-Memory Runtime State Classification

Status: Active Owner: OSHUN Engineering Last Updated: March 23, 2026 Related:
`docs/releases/v1/audits/cross-cutting/in/memory-runtime-state.md`,
`docs/releases/v1/specs/web-app-admin-v1-prd.md`,
`docs/releases/v1/specs/studio-review-and-approval-workflows-dependency-and-data-contract-map.md`,
`docs/releases/v1/specs/studio-background-jobs-and-progress-ux-dependency-and-data-contract-map.md`

## 1. Purpose

This document is the authoritative V1 classification for `V1-ARCH-048`: assign
every audited in-memory runtime-state usage to one of three buckets:

- `acceptable cache`
- `transitional prototype`
- `release blocker`

The source inventory is
`docs/releases/v1/audits/cross-cutting/in/memory-runtime-state.md`.

## 2. Classification Rubric

### 2.1 Acceptable Cache

Use this label when all of the following are true:

- the in-memory state is not the system of record
- losing it on restart does not lose user data, review state, or job state
- the value can be safely recomputed, rehydrated, or repopulated from durable
  systems

### 2.2 Transitional Prototype

Use this label when any of the following are true:

- the state is meaningful product state, but the implementation is clearly
  prototype-oriented and not yet the canonical V1 path
- a durable implementation exists, but memory mode is still exposed as an
  explicit development or fallback option
- restart loss is undesirable, but the state is not one of the PRD's named
  production-complete durability gates

### 2.3 Release Blocker

Use this label when any of the following are true:

- the state is explicitly covered by the PRD durability requirement in section
  `16.4`
- losing the state breaks review, approval, assistant continuity, research
  continuity, or other trust-sensitive user-facing flows
- the in-memory store currently acts as the only practical system of record for
  a quality-critical runtime

## 3. Summary

Classification totals from the audited inventory:

- `acceptable cache`: 2 usages
- `transitional prototype`: 10 usages
- `release blocker`: 12 usages

The release-blocking findings cluster around four themes:

- canonical assistant memory and session state
- review and approval state
- research workflow state
- canonical substrate services still booting on memory-backed stores

## 4. Classification Matrix

| Usage                                                                                                                | Classification           | Rationale                                                                                                                                                       | Primary Follow-On                           |
| -------------------------------------------------------------------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `apps/oshun/bff/src/notifications/preferences-store.ts`                                                              | `transitional prototype` | User-visible preference state should persist, but it is not one of the PRD's named production-complete blocker classes.                                         | `V1-ARCH-049`                               |
| `apps/oshun/bff/src/notifications/read-state-store.ts`                                                               | `transitional prototype` | Read/unread notification state is meaningful continuity state, but not a named release gate in PRD `16.4`.                                                      | `V1-ARCH-049`                               |
| `apps/oshun/bff/src/notifications/digest.ts`                                                                         | `transitional prototype` | Digest scheduling and last-delivery state is user-facing and restart-sensitive, but not a canonical V1 durable system-of-record boundary.                       | `V1-ARCH-049`                               |
| `apps/oshun/bff/src/notifications/quiet-hours.ts`                                                                    | `transitional prototype` | Quiet-hours settings are product state, but they do not fall into the PRD's highest-risk blocker buckets.                                                       | `V1-ARCH-049`                               |
| `apps/oshun/bff/src/routes/device-tokens.ts`                                                                         | `transitional prototype` | Device token registration should be durable before production push delivery, but it is a shell adapter concern rather than the core V1 blocker set.             | `V1-ARCH-049`                               |
| `apps/iris/api/src/services/memory.service.ts`                                                                       | `release blocker`        | This is canonical assistant memory state, explicitly aligned with the PRD's durable-memory requirement and the Iris ownership boundary.                         | `V1-ARCH-049`, `V1-ARCH-052`                |
| `apps/iris/api/src/services/conversation.service.ts`                                                                 | `release blocker`        | Conversation history and assistant continuity are trust-sensitive and restart loss would break replay and continuity expectations.                              | `V1-ARCH-049`, `V1-ARCH-052`                |
| `apps/iris/api/src/services/agent.service.ts`                                                                        | `release blocker`        | Agent and task state requires continuity and auditability once exposed through the canonical assistant substrate.                                               | `V1-ARCH-049`, `V1-ARCH-052`                |
| `apps/iris/api/src/services/knowledge.service.ts`                                                                    | `release blocker`        | User knowledge-base documents and chunks are quality-critical assistant data, not safe ephemeral cache data.                                                    | `V1-ARCH-049`, `V1-ARCH-052`                |
| `services/psyche/orchestrator/src/orchestrator/session/state.py` default memory-backed session state and checkpoints | `release blocker`        | Assistant session state requiring replay or audit is explicitly called out by PRD `16.4`. A default memory-backed state manager is not production-complete.     | `V1-ARCH-049`, `V1-ARCH-052`                |
| `services/psyche/orchestrator/src/orchestrator/caching/semantic_cache.py` memory cache and memory vector-store modes | `acceptable cache`       | This is cache state, not canonical session or job truth. Loss on restart should only reduce reuse efficiency, not corrupt user or workflow records.             | none                                        |
| `apps/sophia/knowledge-graph/src/main.ts` memory-backed knowledge-graph service                                      | `release blocker`        | Sophia is the canonical grounding substrate. A primary service entrypoint that loses graph state on restart is not production-complete.                         | `V1-ARCH-049`, `V1-ARCH-054`                |
| `apps/isis/workflow-registry/src/services/workflow.service.ts` explicit in-memory backend                            | `transitional prototype` | The registry already has a durable PostgreSQL path. The remaining issue is that in-memory mode is still available for a quality-critical control-plane service. | `V1-ARCH-049`                               |
| `apps/isis/gpu-worker/src/workers/gpu-worker.ts` worker-local callbacks and loaded-model registry                    | `acceptable cache`       | This state is local operational cache layered on top of a durable queue and durable job store. It is not the workflow source-of-truth.                          | none                                        |
| `apps/lilith/svc-review/src/app.ts` review queues, items, decisions, assignments, and escalations                    | `release blocker`        | Review state is explicitly named by PRD `16.4` as durability-critical.                                                                                          | `V1-ARCH-049`, `V1-ARCH-050`, `V1-ARCH-051` |
| `apps/lilith/svc-conversation` memory session store, memory fallback, and in-process conversation state              | `release blocker`        | Live assistant session continuity and replay-sensitive state cannot depend on process memory or silent memory fallback.                                         | `V1-ARCH-049`, `V1-ARCH-052`                |
| `apps/lilith/svc-spiritual-guidance/src/conversation-memory.ts` session, journey, and memory stores                  | `release blocker`        | This is assistant continuity and user-journey state, not a disposable cache. Restart loss breaks the intended user experience.                                  | `V1-ARCH-049`, `V1-ARCH-052`                |
| `apps/lilith/bff/src/utils/long-term-memory.ts`                                                                      | `release blocker`        | Long-term assistant memory held in the BFF bypasses the canonical Iris durability boundary and loses state on restart.                                          | `V1-ARCH-049`, `V1-ARCH-052`                |
| `apps/lilith/bff/src/utils/user-preferences.ts`                                                                      | `transitional prototype` | User preferences should persist, but this module is not itself one of the PRD's named release-gate state classes.                                               | `V1-ARCH-049`                               |
| `apps/lilith/bff/src/utils/translation-service.ts`                                                                   | `transitional prototype` | Translation lifecycle state is meaningful product data, but the more urgent release gate is the linked review and approval workflow state.                      | `V1-ARCH-049`                               |
| `apps/lilith/bff/src/utils/translation-review-workflow.ts`                                                           | `release blocker`        | This module directly holds review and approval workflow state in memory.                                                                                        | `V1-ARCH-049`, `V1-ARCH-050`, `V1-ARCH-051` |
| `apps/lilith/bff/src/utils/translation-open-research.ts`                                                             | `release blocker`        | Research submission, review, approval, and publication state is explicitly in the PRD's durability focus area.                                                  | `V1-ARCH-049`, `V1-ARCH-054`                |
| `apps/lilith/bff/src/synthesis-engine.ts` `pendingJobs`                                                              | `transitional prototype` | The module is a mock generation path and not the canonical durable Isis generation control plane, but it should not remain a production-facing job store.       | `V1-ARCH-049`, `V1-ARCH-053`                |
| `apps/lilith/bff/src/api/webhooks/webhook-service.ts` default in-memory storage and delivery queue                   | `transitional prototype` | Delivery continuity matters, but the audited implementation reads like a development-grade integration surface rather than the canonical V1 trust boundary.     | `V1-ARCH-049`                               |

## 5. Consequences

The classification means the V1 sequence should proceed as follows:

1. `V1-ARCH-049` must create explicit replacement plans for every
   `release blocker` listed above.
2. `V1-ARCH-050` and `V1-ARCH-051` should concentrate on the review and approval
   blockers in Lilith review surfaces.
3. `V1-ARCH-052` should concentrate on the Iris, Psyche, Lilith conversation,
   Lilith spiritual-guidance, and Lilith BFF long-term-memory blockers.
4. `V1-ARCH-053` should ensure that any remaining production-facing generation
   job state routes through the durable Isis path.
5. `V1-ARCH-054` should ensure that research workflow state is durably persisted
   in the research-bearing services.

## 6. Notes on Exclusions

The following audited services did not need a runtime-state classification entry
because the inspected in-memory structures were not cross-request service-state
stores:

- `apps/sophia/search-api`
- `apps/isis/generation-api`
- `apps/isis/output-registry`

Those services remain relevant to later durability work, but they did not add
new classified in-memory runtime-state findings in this pass.
