The Athanor Code Flow Map

flowchart LR
    Operator["Operator"] --> App["athanor.exe"]
    Operator --> Manager["athanor-manage<br/>service::dispatch"]
    Manager --> Plan["runtime_plan"]
    Plan --> Supervisor["Supervisor::run"]

    subgraph Children["Managed service children"]
        PG[("PostgreSQL<br/>AKASHA authority")]
        NATS["NATS JetStream<br/>transport, not authority"]
        Delivery["athanor-delivery<br/>PostgreSQL ↔ NATS bridge"]
    end

    Supervisor --> PG
    Supervisor --> NATS
    Supervisor --> Delivery
    App --> Host["one in-process<br/>multi-room Host"]

    OMP["OMP adapter"] <-->|"authenticated Host WebSocket"| Host
    OMP <-->|"long-lived JSONL child stdio"| Substrate["athanor-substrate"]

    Substrate <-->|"durable organ reads and writes"| PG
    Substrate <-->|"Vault profile only"| Vault[("room-attributed files")]
    Substrate -.->|"query embeddings"| Ollama["Ollama<br/>inference only"]
    Substrate --> GigaWorker["GIGA worker task<br/>inside substrate process"]
    GigaWorker <-->|"claim events / store candidates"| PG
    GigaWorker -.->|"bounded classifier / extraction"| Ollama

    PG -->|"claim crane_outbox rows"| Delivery
    Delivery -->|"mark published / record receipts"| PG
    Delivery -->|"publish and consume Crane subjects"| NATS
    NATS -->|"JetStream acknowledgements"| Delivery
    NATS -->|"sanitized receipt stream"| Host
    Host --> HostState[("room-scoped Host projection state")]

flowchart BT
    Hearth["hearth"]
    Origami["origami"]
    Summoning["summoning"]
    Protocol["protocol"]
    Vault["vault"]
    Akasha["akasha"]
    Host["host"]
    Keeper["omp-keeper"]
    Interactive["interactive-process"]
    Install["athanor-install"]
    Godot["parked athanor-godot<br/>gui/src"]

    Origami --> Hearth
    Summoning --> Hearth
    Summoning --> Origami
    Protocol --> Hearth
    Protocol --> Origami
    Protocol --> Summoning
    Akasha --> Hearth
    Akasha --> Protocol
    Akasha --> Vault
    Akasha --> Origami
    Akasha --> Summoning
    Host --> Akasha
    Host --> Hearth
    Host --> Origami
    Host --> Protocol
    Host --> Summoning
    Keeper --> Protocol
    Keeper --> Interactive
    Install --> Host
    Install --> Hearth
    Install --> Protocol
    Install --> Interactive
    Install --> Keeper
    Godot -->|parked client dependency| Protocol

sequenceDiagram
    participant SCM as Operator / Windows SCM
    participant Manage as athanor-manage service::dispatch
    participant Layout as current.json + config + secrets
    participant Plan as runtime_plan
    participant Sup as Supervisor::run
    participant PG as managed PostgreSQL
    participant NATS as NATS
    participant Delivery as delivery

    SCM->>Manage: start
    Manage->>Layout: resolve the active version and service topology
    Manage->>Plan: build the ordered ProcessSpec list
    Plan-->>Sup: PostgreSQL? -> NATS -> delivery
    opt managed database mode
        Sup->>PG: spawn and await readiness
    end
    Sup->>NATS: spawn and await readiness
    Sup->>Delivery: spawn and await readiness
    Sup-->>SCM: report RUNNING

    SCM->>Manage: stop
    Manage->>Sup: stop the process plan
    Sup->>Delivery: stop
    Sup->>NATS: stop
    opt managed database mode
        Sup->>PG: stop
    end

sequenceDiagram
    participant Pi as OMP context hook
    participant Adapter as adapters/omp/index.ts
    participant Host as Athanor Host
    participant Rust as RustJsonlTransport
    participant Data as substrate or Vault

    Pi->>Adapter: context event
    Adapter->>Adapter: load room directives, room state, active-spirit snapshot
    opt enabled room model default
        Adapter->>Adapter: resolve and apply model selector
    end
    Adapter->>Host: write conversation log
    Adapter-->>Rust: detached GIGA conversation ingest
    Adapter->>Adapter: inspect turn-addition memo/cache

    alt byte-stable memo hit
        Adapter->>Adapter: replay memoized additions
    else cache miss
        Adapter->>Host: analyze_context
        Host-->>Adapter: query classification and lane hints
        Adapter->>Adapter: add room and routing reminders
        opt fresh session
            Adapter->>Rust: paper_boat_wake
            Rust->>Data: load latest Boat and later unboated memories
            Adapter->>Rust: anamnesis read
        end
        Adapter->>Adapter: keyword directive
        Adapter->>Adapter: deterministic process-lesson plan
        Adapter->>Adapter: prose lesson-trigger matches
        Adapter->>Adapter: inspect Recall Policy
        opt unresolved entity affects classification
            Adapter->>Rust: entity_resolve
            Rust-->>Adapter: canonical entity evidence
            Adapter->>Host: analyze_context again
        end
        Adapter->>Host: evaluate Recall Policy
        alt Vault profile
            Adapter->>Rust: vault_recall
            Rust->>Data: file-authoritative bounded retrieval
        else AKASHA profile
            Adapter->>Rust: recall
            Rust->>Data: PostgreSQL-authoritative retrieval
        end
        Adapter->>Host: apply_viewport
        alt refresh succeeds
            Adapter->>Host: complete_refresh
        else refresh fails
            Adapter->>Host: fail_refresh
        end
        Adapter->>Adapter: record recall telemetry
        Adapter->>Adapter: memoize byte-stable additions
    end
    Adapter-->>Pi: anchor additions after the current user turn

flowchart LR
    Compact["session_compact"] --> Strip["remove recall working set"]
    Strip --> Invalidate["Host invalidateAfterCompaction"]

    Task["task tool_call / progress / lifecycle / result"] --> Normalize["Host lineage normalize / settle"]
    Normalize --> Lineage["write lineage memories"]

    End["agent_end"] --> Capture["capture final conversation"]
    Capture --> Giga["detached GIGA ingest"]

    Shutdown["shutdown"] --> Close["close Host and Rust transports"]

flowchart LR
    Tools["tools.ts registrations"] --> Local["adapter-local handlers"]
    Tools --> HostClient["Host command clients"]
    Tools --> RT["RustJsonlTransport.request"]

    Local --> Files[("room files / OMP session state")]
    HostClient <-->|"authenticated WebSocket"| Host["multi-room Host router"]

    RT --> Ensure["ensureStarted"]
    Ensure --> Queue["queue and flush stdin line"]
    Queue --> Main["athanor-substrate main"]
    Main --> Decode["decode response stdout line"]
    Decode --> Handle["handleLine"]
    Handle --> RT

    Timeout["timeout after definitive dispatch"] --> Unknown["outcome unknown<br/>do not retry as if unsent"]
    RT -.-> Timeout

flowchart TD
    Stdin["stdin JSONL"] --> Main["main.rs line loop"]
    Main --> Req{"ProtocolRequest"}

    Req --> Vault["vault_recall"]
    Vault --> VaultCrate["vault<br/>no database initialization"]

    Req --> Pre["health / migrations<br/>pre-init paths"]

    Req --> NeedDB["database-backed request"]
    NeedDB --> Lazy["lazy Config::from_env + pool"]
    Lazy --> Worker["spawn_giga_worker when enabled"]
    Lazy --> Router{"request family"}

    Router --> Continuity["canon, remember, paper boat,<br/>recall, entity, anamnesis"]
    Router --> Knowledge["lesson, lesson context/triggers,<br/>design documents, cluster"]
    Router --> Social["Hallway create/join/post/read/inbox<br/>Knock policy/create"]
    Router --> Giga["GIGA ingest, queue, worker,<br/>review, promotion, health"]
    Router --> Ops["substrate health and maintenance"]

    Continuity --> PG[("PostgreSQL")]
    Knowledge --> PG
    Social --> PG
    Giga --> PG
    Ops --> PG
    Worker -.-> Giga

    PG --> Resp["ProtocolResponse"]
    VaultCrate --> Resp
    Pre --> Resp
    Resp --> Stdout["stdout JSONL"]

flowchart TD
    Q["recall request"] --> Validate["validate and normalize"]
    Validate --> Parse["extract dates and terms<br/>rooms = room + house"]
    Parse --> Embed["optional Ollama query embedding"]

    Parse --> BM["BM25F candidates"]
    Parse --> Vocab["nearest semantic vocabulary"]
    Vocab --> Bridge["BM25F concept bridge"]
    Embed --> Vector["pgvector semantic chunks"]
    Parse --> Trgm["pg_trgm word-similarity chunks"]
    Parse --> Dates["date matches"]
    Parse --> Threads["lexical thread rows"]

    BM --> Fuse["weighted rank fusion"]
    Bridge --> Fuse
    Vector --> Fuse
    Trgm --> Fuse
    Dates --> Fuse
    Threads --> Fuse

    Fuse --> Bound["dedupe and truncate"]
    Bound --> Neighbors["hydrate thread-neighbor graph"]
    Neighbors --> Canon["attach active canon matches"]
    Canon --> Cluster["attach cluster resonance"]
    Cluster --> Result["evidence + taxonomy + warnings"]

flowchart TD
    Q["vault_recall request"] --> Marker["load .athanor-room.json"]
    Marker --> Collect["collect eligible attributed files<br/>respect ignores and limits"]
    Collect --> Parse["parse Markdown / JSON / JSONL / text"]
    Parse --> Docs["in-memory documents"]
    Docs --> Rank["BM25F rank"]
    Rank --> Bound["bounded attributed candidates"]

    NoDB["No PostgreSQL<br/>No writes"] -.-> Q

flowchart TD
    App["athanor.exe"] --> Start["host::start"]
    Start --> House["open_house"]
    House --> Pool["one shared PostgreSQL pool"]
    House --> Listener["one loopback listener"]
    House --> Rooms["nest /room/<key>"]
    Rooms --> New["Host::new for each room"]
    New --> Load["load room state, cursor,<br/>sessions, receipts, ReceiptTracker"]
    Load --> Axum["Axum room routes"]
    New -.-> Bridge["run_receipt_bridge<br/>when NATS configured"]
    Axum --> Socket["handle_socket"]
    Socket --> Text["process_text"]
    Text --> JSON["parse JSON"]
    JSON --> Hash["semantic hash"]
    Hash --> Parse["parse_client_command"]
    Parse --> Validate["validate room/spirit/session binding,<br/>expiry and hop bounds"]
    Validate --> Route{"command router"}

    Route --> Receipt["receipt / recall subscribe,<br/>resync, ack"]
    Route --> Policy["Recall Policy set/evaluate/<br/>complete/fail/invalidate"]
    Route --> Context["analyze_context / apply_viewport"]
    Route --> Routing["lane status / dispatch / familiar status"]
    Route --> Lineage["lineage normalize / settle"]
    Route --> Shell["conversation log / lesson plan / braid"]

    Policy --> Mutate["commit_change"]
    Receipt --> Mutate
    Context --> Reply["typed direct event"]
    Routing --> Reply
    Lineage --> Reply
    Shell --> Reply

    Mutate --> Version["compute mutations, version, state hash"]
    Version --> Store["persist policy, sessions, cursor,<br/>idempotency receipt"]
    Store --> Reply
    Store --> Delta["broadcast ordered delta"]
    Reply --> Socket
    Delta --> Socket

    Validate -->|"invalid"| Reject["typed rejection; no mutation"]
    Bridge --> Tracker["filter accepted / duplicate / stale /<br/>foreign / malformed receipts"]
    Tracker --> Delta

sequenceDiagram
    participant Tool as OMP sleep tool
    participant Sub as paper_boat_sleep
    participant PG as PostgreSQL
    participant Delivery as DeliveryService
    participant NATS as JetStream
    participant Host as Host receipt bridge
    participant Godot as Parked Godot client

    Tool->>Sub: room + standalone Boat body
    Sub->>Sub: hash db-only source path and prepare memory
    Sub->>PG: BEGIN
    Sub->>PG: write_memory_tx + continuation graph
    PG->>PG: trigger inserts crane_outbox boat.ready
    Sub->>PG: select outbox event id
    Sub->>PG: COMMIT
    opt configured filesystem backup
        Sub->>Sub: post-write backup
    end
    Sub-->>Tool: durable receipt

    Delivery->>PG: Store::claim_next
    PG-->>Delivery: pending Crane outbox row
    Delivery->>Delivery: parse and validate CraneEvent
    Delivery->>NATS: Broker::publish lane subject
    NATS-->>Delivery: publish acknowledgement
    Delivery->>PG: Store::mark_published

    NATS-->>Delivery: consume boat.ready before addressed Crane
    Delivery->>Delivery: enforce subject, lane, recipient, expiry
    Delivery->>PG: Store::record_receipt authoritative transaction
    Delivery->>NATS: sanitized BoatReceiptProjection
    Delivery->>NATS: acknowledge consumed event
    NATS-->>Host: receipt stream
    Host->>Host: ReceiptTracker classification
    Host-->>Godot: historical client receipt snapshot / delta

flowchart TD
    Conversation["OMP conversation"] --> Capture["capture transcript + private source ledger"]
    Capture --> Ingest["GIGA conversation ingest<br/>bounded turn windows"]
    Ingest --> Events[("PostgreSQL<br/>giga_events: pending")]

    Events --> Claim["worker claim"]
    Claim --> Validate["validate claim and event bounds"]
    Validate --> Sources["resolve exact private-ledger sources"]
    Sources --> Ollama["Ollama inference<br/>gate + extraction only"]
    Ollama --> Decision{"worthy candidate?"}
    Decision -->|"no"| Finish["finish event without candidate"]
    Decision -->|"yes"| Store["atomically store one GigaCandidate<br/>in PostgreSQL and finish event"]
    Validate -->|"retryable failure"| Retry["bounded retry then failed"]

    Store --> Proposal["candidate proposal<br/>not authority"]
    Proposal --> Review["giga_review"]
    Review --> ReviewChecks["trusted room + reviewer identity +<br/>current state + exact source resonance"]
    ReviewChecks --> InReview["durable PostgreSQL<br/>in_review transition"]

    InReview --> Promote{"promotion tool"}
    Promote --> Authority["re-check authority, state, and sources"]
    Authority --> Memory["transactional memory write"]
    Authority --> Coding["transactional coding lesson write"]
    Authority --> Consent["explicit project publication consent"]
    Consent --> Project["transactional project lesson write"]
    Memory --> Record["record promotion"]
    Coding --> Record
    Project --> Record

flowchart LR
    Pins["installer/dependencies.json"] --> Fetch["fetch pinned PostgreSQL,<br/>pgvector, NATS, parked Godot"]
    Fetch --> Verify["hash verification + cache"]
    Verify --> Cargo["cargo release-build<br/>five binaries + parked Godot cdylib"]
    Cargo --> Stage["stage runtime, adapter, parked Godot, manager"]
    Stage --> Import["parked Godot headless import"]
    Import --> Manifest["hash payload and emit release manifest"]

flowchart TD
    Start["ReleaseManifest validate"] --> Config["load House config"]
    Config --> Preflight["platform + payload hash preflight"]
    Preflight --> Mutable["create and ACL-restrict mutable dirs<br/>and room state"]
    Mutable --> Legacy["one-time legacy import"]
    Legacy --> Backup["pre-upgrade database backup"]
    Backup --> Stop["stop service"]
    Stop --> Stage["stage, copy, write manifest,<br/>atomic version rename"]
    Stage --> Stable["update stable manager, runtime config,<br/>secrets, OMP client projection"]
    Stable --> Pointer["atomically update current.json"]
    Pointer --> Migrate["run production migration registry"]
    Migrate --> Service["install or update Windows service"]
    Service --> Run["start service and await health"]
    Run -->|"ready"| Loader["register stable OMP loader"]

    Stage -->|"failure"| Restore["restore pointer and database;<br/>remove failed first install"]
    Stable -->|"failure"| Restore
    Pointer -->|"failure"| Restore
    Migrate -->|"failure"| Restore
    Run -->|"failure"| Rollback["rollback to prior release"]

flowchart TD
    Rollback["rollback command"] --> Undo["take undo backup"]
    Undo --> Stop["stop service"]
    Stop --> Pointer["flip current pointer to prior version"]
    Pointer --> DB["restore prior database backup"]
    DB --> Start["start and await readiness"]
    Start -->|"failure"| Newer["restore newer release"]

    Uninstall["uninstall"] --> Remove["remove service, operator integration,<br/>and program files"]
    Remove --> Preserve["preserve operator data"]
    Purge["purge + explicit confirmation"] --> Destroy["remove operator data"]

flowchart TD
    Host["Athanor Host"] <-->|WebSocket: parked client| Session["AthanorHostSession"]
    Session -->|"owns credentials and transport"| Link["HostLink"]
    Session --> Protocol["protocol.rs<br/>wire vocabulary, parsers, delta application"]
    Protocol --> Shell["shell.rs router"]

    Shell --> Resume["Resume"]
    Shell --> Policy["RecallPolicy"]
    Shell --> Routing["Routing"]
    Shell --> Familiar["Familiars"]
    Shell --> Dispatch["Dispatch"]
    Shell --> Health["Health"]

    Policy -->|"only authored mutation"| Requested["requested Recall mode"]
    Routing --> ReadOnly["read-only projections"]
    Familiar --> ReadOnly
    Health --> ReadOnly
    Dispatch --> Packet["validated OMP spawn packet<br/>never executes it"]

    Session --> Boat["PaperBoatReceipt state"]
    Boat --> Chat["S01ChatCenter"]
    Chat --> Composer["Composer<br/>visibly disabled: no conversation command"]
    Chat --> Message["MessageCard"]
    Chat --> Receipt["ReceiptCard"]
    Chat --> Disclosure["DisclosureBanner"]
    Shell --> Nav["ReliquaryNavigator"]

    Effects["Effects Lab"] -.-> Juicee["third-party Juicee plugin"]
    Prototype["gui-prototype/<br/>read-only operator surface"] --> Proxy["serve.ts: loopback proxy"]
    Proxy -->|nine POST-only /live/* read routes| Host