%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart TB
  Client["LLM host / MCP client"] --> Access["Authenticated access layer"]
  Browser["User and operator portals"] --> Access
  Access --> Services["Team-scoped application services"]

  Services --> Remember["Remember"]
  Services --> Recall["Recall"]
  Services --> Trace["Trace and correction"]
  Services --> Control["Control plane"]
  Services --> Dream["Dreaming"]

  Remember --> Providers["Reviewer, verifier,<br/>and embedding providers"]
  Recall --> Providers
  Dream --> Providers

  Remember --> PG[("PostgreSQL + pgvector<br/>single source of truth")]
  Recall --> PG
  Trace --> PG
  Control --> PG
  Dream --> PG

  Services -. "optional coordination" .-> Redis[("Redis or one-process memory")]

%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart LR
  Request["Authenticated request"] --> Kind{"Operation"}
  Kind -- remember --> Write["Stage evidence and queue placement"]
  Kind -- recall --> Read["Search and bounded adjacency"]
  Kind -- trace --> Trace["Read provenance and current graph"]
  Kind -- review/correct --> Correct["Append decision and recompute"]
  Kind -- control --> Admin["Manage scoped control state"]

  Write --> PG["PostgreSQL transaction"]
  Read --> PG
  Trace --> PG
  Correct --> PG
  Admin --> PG

%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart LR
  Transport["MCP and first-party portals"] --> Application["Application services"]
  Application --> Domain["Domain contracts and policy"]
  Application --> Ports["Repository, provider,<br/>and coordination ports"]
  PG["PostgreSQL adapter"] --> Ports
  Redis["Optional Redis adapter"] --> Ports
  AI["AI provider adapters"] --> Ports

%%{init: {"sequence": {"rightAngles": true}}}%%
sequenceDiagram
  autonumber
  participant S as Server
  participant P as PostgreSQL
  participant R as Redis or process memory
  participant A as Model providers
  participant W as Workers
  participant H as HTTP
  actor O as Operator

  S->>S: Load and validate configuration
  S->>P: Connect and inspect release/migration state
  S->>H: Start health and control surfaces
  alt Migration required in 2.1.x
    S->>H: Enter maintenance and log migration_required
    O->>H: Start or resume after preflight
    S->>A: Validate migration provider contracts
    S->>P: Run official-pipeline migration and hard gates
    P-->>S: Commit automatic cutover marker
    S->>S: Close legacy migration adapter
  else Compatible completed marker
    S->>P: Continue normal release startup
  end
  S->>P: Apply compatible schema migrations
  S->>P: Validate pgvector, embedding contract, and search-index profile
  S->>R: Build required coordination backend
  S->>A: Validate configured provider contracts
  S->>W: Start placement, embedding, cleanup, and optional schedulers
  S->>H: Enable main v2 data plane
  H-->>S: Serve until termination
  S->>H: Stop accepting traffic
  S->>W: Drain or release work safely
  S->>S: Close providers and adapters

%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart LR
  Evidence["Evidence fragments"] --> Observation["Relationship observations"]
  Observation --> Verification["Verification events"]
  Verification --> Current["Profile-owned Relationship current state"]
  Current --> Cross["Cross-profile reference ledger"]
  Current --> Edge["SemanticEdge read<br/>active validated/fact only"]
  Current --> Trace["Trace with support and history"]
  Current --> Dream["Optional isolated Hypotheses"]

%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart LR
  Request["Authenticated bounded request"] --> Scan{"Pass, guarded,<br/>or quarantine?"}
  Scan -- quarantine --> StageQ["Commit quarantined intake"]
  StageQ --> Quarantine["Restricted audit only"]
  Scan -- pass or guarded --> Intake["Commit evidence and queue intent"]
  Intake --> Extract["Structure extraction"]
  Extract --> ExtractSignal{"Reviewer security signal?"}
  ExtractSignal -- Yes --> Quarantine
  ExtractSignal -- No --> Context["Server Entity/predicate context"]
  Context --> Verify["One verifier response"]
  Verify --> Validate["Closed-schema, security-signal,<br/>and allowlist validation"]
  Validate --> Signal{"Model security signal?"}
  Signal -- Yes --> Quarantine
  Signal -- No --> Policy["Deterministic lifecycle"]
  Policy --> Commit["One PostgreSQL transaction"]
  Commit --> Immediate["Current rows, SemanticEdges,<br/>and full-text available"]
  Commit --> Async["Versioned embedding job"]

%%{init: {"sequence": {"rightAngles": true}}}%%
sequenceDiagram
  participant W as Placement worker
  participant P as PostgreSQL
  participant E as Embedding worker

  W->>P: Begin semantic transaction
  W->>P: Append evidence decisions and transitions
  W->>P: Update current Entity / Relationship rows
  W->>P: Upsert search document and embedding job
  W->>P: Commit
  P-->>W: Authoritative state and SemanticEdge visibility
  E->>P: Claim embedding job
  E->>P: Write vector only for matching source version

%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart LR
  Contract["1. Versioned domain contracts"] --> Schema["2. PostgreSQL schema<br/>and repositories"]
  Schema --> Remember["3. Remember + strict verifier"]
  Remember --> Recall["4. Recall + trace"]
  Recall --> Dream["5. Candidate-safe dreaming"]
  Dream --> Migration["6. 2.1.x official-pipeline<br/>legacy migration"]
  Migration --> Cutover["7. Automatic cutover"]
  Cutover --> Remove["8. Remove Neo4j bridge<br/>in 2.2.0"]