BSFG Interaction Diagrams

1. Ingress Fact Flow (Append -> Handoff -> Confirm)

sequenceDiagram
  participant P as Producer (External)
  participant ER as External BSFG RPC
  participant ISB as ISB
  participant IR as Internal BSFG Receiver
  participant IFB as IFB
  participant C as Consumer (Internal)

  P->>ER: AppendFact(fact, envelope)
  ER->>ISB: append(payload, metadata)
  ISB-->>ER: offset=n (durable)
  ER-->>P: ack {offset:n}

  IR->>ISB: FetchFacts(consumer, from=n)
  ISB-->>IR: batch[n..m]
  IR->>IFB: putIfAbsent(idempotencyKey, payload)
  IFB-->>IR: Inserted | AlreadyExists
  IR->>ISB: ConfirmReceipt(consumer, m)

  C->>IFB: FetchFacts(local consumer)
  IFB-->>C: fact batch

2. Egress Fact Flow (Reverse Direction)

sequenceDiagram
  participant Pi as Producer (Internal)
  participant IR as Internal BSFG RPC
  participant ESB as ESB
  participant ER as External BSFG Receiver
  participant EFB as EFB
  participant Ce as Consumer (External)

  Pi->>IR: AppendFact(fact, envelope)
  IR->>ESB: append(payload, metadata)
  ESB-->>IR: offset=k (durable)
  IR-->>Pi: ack {offset:k}

  ER->>ESB: FetchFacts(consumer, from=k)
  ESB-->>ER: batch[k..x]
  ER->>EFB: putIfAbsent(idempotencyKey, payload)
  EFB-->>ER: Inserted | AlreadyExists
  ER->>ESB: ConfirmReceipt(consumer, x)

  Ce->>EFB: FetchFacts(local consumer)
  EFB-->>Ce: fact batch

3. Partition + Reconciliation

sequenceDiagram
  participant ISB as Store Buffer
  participant IFB as Forward Buffer
  participant CT as Cursor Tracker

  Note over ISB,IFB: Partition (gate closed)
  ISB->>ISB: continue appends (durable)
  CT-->>CT: frontier frozen

  Note over ISB,IFB: Reconnect (gate opening)
  CT->>ISB: read frontier+1
  ISB-->>IFB: replay backlog
  IFB-->>ISB: dedupe outcomes
  ISB->>CT: advance contiguous frontier
  Note over ISB,IFB: normal mode restored

4. Artifact Exchange (Out-of-Band)

sequenceDiagram
  participant P as Producer
  participant RPC as BSFG RPC
  participant OS as Object Store
  participant C as Consumer

  P->>RPC: PutObject(blob)
  RPC->>OS: store(blob)
  OS-->>RPC: digest,size,key
  RPC-->>P: object_ref

  P->>RPC: AppendFact(..., object_ref)
  RPC-->>C: fact with object_ref
  C->>RPC: GetObject(object_ref)
  RPC->>OS: fetch(key)
  OS-->>RPC: blob
  RPC-->>C: blob