bience — EARS Specification & Flows

graph TD
    F["Foundations<br/>Terraform, repo, Infisical,<br/>Postgres, audit chain"]

    PERM["Permission core<br/>family graph"]
    CNS["Consent service"]
    VOICE["Voice loop<br/>Pipecat, STT, LLM, TTS"]
    SAFE["Safety classifier<br/>parallel path"]
    CON["Reviewer console<br/>the fifth surface"]
    DEG["Degradation cache"]
    TRN["Voice-driven transparency<br/>and access removal"]

    S1["Surface 1<br/>elder phone line"]
    DIG["Digest<br/>SMS and email"]
    S2W["Surface 2<br/>mobile web"]
    S4M["Surface 4 minimal<br/>closure, export, audit log"]
    S2N["Surface 2 native"]
    S4F["Surface 4 full"]
    VEE["Vee adult"]
    VEE18["Vee under-18"]

    LAUNCH{{"Launch gate<br/>50 families"}}

    F --> PERM
    F --> VOICE
    F --> CNS
    PERM --> CNS
    PERM --> CON
    PERM --> TRN
    VOICE --> SAFE
    SAFE --> CON
    VOICE --> DEG

    PERM --> S1
    CNS --> S1
    SAFE --> S1
    DEG --> S1
    CON --> S1
    TRN --> S1

    S1 --> LAUNCH
    S1 --> DIG
    DIG --> LAUNCH

    LAUNCH --> S2W
    LAUNCH --> S4M
    S2W --> S2N
    S4M --> S4F
    S2W --> VEE
    VEE --> VEE18

gantt
    dateFormat YYYY-MM-DD
    axisFormat %b
    title Non-code lead-time items — durations only

    section Telephony
    UK number provisioning and validation :a1, 2026-08-01, 30d

    section People
    DBS checks for reviewers              :b1, 2026-08-01, 60d
    Safeguarding partnerships             :b2, 2026-08-01, 120d

    section Legal
    ICO registration and DPO              :c3, 2026-08-01, 30d
    DPIA                                  :c2, 2026-08-15, 45d
    Consent flow legal review             :c1, 2026-08-15, 60d

    section Assurance
    Cyber Essentials Plus                 :d1, 2026-10-01, 60d
    Penetration test                      :d2, 2026-12-01, 30d

    section Distribution
    App Store review cycle                :e1, 2027-01-01, 21d

graph LR
    N["Order UK number<br/>DAY ONE"] --> W1
    subgraph W1["Weekend 1 — the loop"]
        A["Pipecat local"] --> B["Chime SIP in"]
        B --> C["Transcribe + Bedrock + Polly"]
        C --> D["Per-stage latency,<br/>both clocks"]
    end
    subgraph W2["Weekend 2 — the interesting part"]
        E["Classifier parallel path"] --> G["Interrupt channel"]
        G --> H["Consent script"]
        H --> I["Audit hash chain"]
        I --> J["Synthetic corpus run"]
    end
    W1 --> W2
    W2 --> K["Latency table, both clocks<br/>failure-rate table<br/>recorded interrupt"]

    N -.->|"if number stalls"| WEB["WebRTC fallback<br/>same pipeline, no PSTN"]
    WEB --> W1

flowchart TD
    START(["Call connects"]) --> DISC["State: AI assistant<br/>and recording notice"]
    DISC --> IDQ{"Speaker<br/>identified?"}

    IDQ -->|"No match"| CONF["Conversational<br/>confirmation"]
    IDQ -->|"Voiceprint hypothesis"| CONF
    CONF --> REG{"Registered in<br/>family graph?"}

    REG -->|No| UNREG["Unregistered-speaker script<br/>purpose only, no disclosure"]
    UNREG --> ENDC(["End within 2 turns"])

    REG -->|Yes| CONS{"Consent<br/>recorded?"}
    CONS -->|No| CAPTURE["Consent capture<br/>see 3.2"]
    CONS -->|Yes| SCOPE["Resolve permission scope<br/>and config for THIS person"]

    SCOPE --> TURN["Conversation turn"]
    TURN --> CHANGE{"Speaker<br/>changed?"}
    CHANGE -->|Yes| IDQ
    CHANGE -->|No| FANOUT["Fan out to<br/>safety classifier"]
    CHANGE -->|No| GEN["Generate response<br/>pre-filtered context"]
    GEN --> POST["Post-check against<br/>permission scope"]
    POST --> SPEAK["Speak"]
    SPEAK --> MORE{"Continue?"}
    MORE -->|Yes| TURN
    MORE -->|No| CLOSE(["Close and summarise"])

    FANOUT -.->|"immediate severity"| INT["Interrupt<br/>see 3.4"]

flowchart TD
    S(["First conversation"]) --> EXPL["Explain: who is calling,<br/>who arranged it, what is recorded,<br/>what is kept, who can see it,<br/>how to stop it"]
    EXPL --> CAP{"Capacity<br/>indicators?"}

    CAP -->|"Indicators present"| EXIT["Exit consent flow"]
    EXIT --> FLAG["Raise capacity-review flag"]
    FLAG --> NOSTATE["Consent state:<br/>not obtained"]
    NOSTATE --> ENDA(["Close courteously"])

    CAP -->|"No indicators"| ASK["Ask for consent"]
    ASK --> ANS{"Consent<br/>given?"}

    ANS -->|Yes| REC["Record consent<br/>per purpose, per domain"]
    REC --> TRANS["Present transparency<br/>statement"]
    TRANS --> PROCEED(["Proceed to conversation"])

    ANS -->|No| DECL["Consent-declined<br/>closing script"]
    DECL --> SUSP["Suspend all calls"]
    SUSP --> DEL["Delete call audio<br/>within 1 hour"]
    DEL --> NOTIF["Notify carer:<br/>no content disclosed"]
    NOTIF --> ENDB(["End"])

flowchart TD
    Q(["Elder asks a<br/>transparency question"]) --> TYPE{"Which?"}
    TYPE -->|"What can they see?"| CATS["State categories<br/>and named people"]
    TYPE -->|"What was in the summary?"| SUM["State most recent<br/>digest contents"]
    TYPE -->|"What happened recently?"| LOG["Spoken 30-day<br/>sharing log"]
    TYPE -->|"Remove someone"| REM["Confirm the named person"]

    REM --> APPLY["Apply removal<br/>subject overrides account holder"]
    APPLY --> NOTE["Record in audit"]
    NOTE --> CONFIRM["Confirm on next call"]

    CATS --> DONE(["Return to conversation"])
    SUM --> DONE
    LOG --> DONE
    CONFIRM --> DONE

sequenceDiagram
    autonumber
    participant W as Voice worker
    participant C as Safety classifier
    participant L as Lide orchestrator
    participant S as Safeguarding service
    participant R as Reviewer

    W->>C: turn text (parallel, non-blocking)
    W->>L: turn text
    L-->>W: streamed response

    alt Immediate severity
        C-->>W: interrupt
        W->>W: stop current audio
        W-->>W: immediate-severity script
        C->>S: flag, immediate
        S->>R: notify within target
    else Review severity or ambiguous
        C->>S: flag, review
        S->>R: queue
        Note over W: conversation continues normally
    else Verdict late
        C--)S: out-of-band escalation
        Note over W: turn already completed
    else Classifier unavailable
        W->>W: degraded-mode script only
        Note over W,L: no unclassified<br/>open conversation
    end

    R->>S: decision, rationale, action
    S->>S: record outcome

flowchart TD
    H["Health check"] --> Q1{"Classifier<br/>available?"}
    Q1 -->|No| DEGONLY["Degraded-mode script only<br/>no unclassified conversation"]
    Q1 -->|Yes| Q2{"Audit<br/>writable?"}
    Q2 -->|No| DENY["Deny data access"]
    Q2 -->|Yes| Q3{"STT<br/>available?"}
    Q3 -->|"Primary down"| STT2["Secondary STT"]
    Q3 -->|"None"| DEGONLY
    Q3 -->|Yes| Q4{"LLM<br/>available?"}
    STT2 --> Q4
    Q4 -->|"Primary down"| LLM2["Secondary vendor"]
    Q4 -->|"None"| PRE["Pre-written apology<br/>and callback offer"]
    Q4 -->|Yes| NORMAL["Normal conversation"]
    LLM2 --> NORMAL
    PRE --> ENDD(["End call gracefully"])
    DEGONLY --> NOTIFY["Notify carer:<br/>contact did not complete normally"]
    DENY --> NOTIFY
    ENDD --> NOTIFY

flowchart LR
    T["Transcript"] --> EX["Extract observed<br/>statements and events"]
    EX --> CITE["Attach source<br/>call and turn range"]
    CITE --> SAFETY{"Safety-relevant<br/>event present?"}
    SAFETY -->|Yes| HEAD["Place at head<br/>of digest"]
    SAFETY -->|No| BODY["Body"]
    HEAD --> SCOPE
    BODY --> SCOPE["Apply recipient<br/>permission scope"]
    SCOPE --> MULTI{"More than one<br/>recipient?"}
    MULTI -->|Yes| PER["One digest<br/>per scope"]
    MULTI -->|No| ONE["Single digest"]
    PER --> GAPS
    ONE --> GAPS["Mark unraised topics<br/>as NOT DISCUSSED"]
    GAPS --> SEND["Deliver"]

flowchart LR
    S(["User stops<br/>speaking"]) --> VAD["Silence threshold<br/>1,200 ms"]
    VAD --> EOT{{"End-of-turn<br/>detected"}}
    EOT --> STT["STT final<br/>100-200 ms"]
    STT --> CTX["Auth + context<br/>30-50 ms"]
    CTX --> LLM["LLM first token<br/>300-500 ms"]
    LLM --> TTS["TTS first byte<br/>80-150 ms"]
    TTS --> OUT(["Persona audio<br/>starts"])

    EOT -.->|"VOI-001 response latency 800 ms"| OUT
    S -.->|"VOI-021 perceived gap 2200 ms"| OUT

stateDiagram-v2
    [*] --> NotObtained
    NotObtained --> CaptureInProgress : first conversation
    CaptureInProgress --> Obtained : consent given
    CaptureInProgress --> Declined : consent refused
    CaptureInProgress --> CapacityReview : capacity indicators
    CapacityReview --> LPAAuthorised : verified LPA, in scope
    CapacityReview --> NotObtained : review inconclusive
    LPAAuthorised --> Obtained : within LPA scope only
    Obtained --> Withdrawn : withdrawal at any time
    Obtained --> ReconfirmDue : fluctuating capacity interval
    ReconfirmDue --> Obtained : reconfirmed
    ReconfirmDue --> HumanReview : reconfirmation missed
    HumanReview --> Obtained : resolved
    Withdrawn --> [*]
    Declined --> [*]

    note right of LPAAuthorised
        Health and Welfare LPA operates only
        on incapacity. Property and Financial
        Affairs may operate with capacity.
        Whether an attorney can give UK GDPR
        consent at all is unsettled. OD-02.
    end note

stateDiagram-v2
    [*] --> Raised
    Raised --> Acknowledged : reviewer picks up
    Raised --> Escalated : SLA breached
    Escalated --> Acknowledged : next tier picks up
    Acknowledged --> UnderReview
    UnderReview --> NoAction : recorded rationale
    UnderReview --> InternalAction : carer notified
    UnderReview --> OutwardReferral : LA, Action Fraud, bank
    OutwardReferral --> AwaitingOutcome
    AwaitingOutcome --> Closed : outcome recorded
    NoAction --> Closed
    InternalAction --> Closed
    Closed --> [*]

    note right of InternalAction
        Guard on the transition, not a step
        inside it: if the carer is a subject
        of the concern, exclude them from
        all notification. SFG-010.
    end note

stateDiagram-v2
    [*] --> Trial
    Trial --> Active : converts, first charge
    Trial --> Lapsed : trial ends without conversion
    Active --> Dunning : payment fails
    Dunning --> Active : payment recovers
    Dunning --> Lapsed : dunning schedule exhausted
    Active --> Cancelled : subscriber cancels
    Active --> Bereaved : elder recorded deceased
    Bereaved --> Closed : bereavement policy period
    Lapsed --> Closed
    Cancelled --> Closed
    Closed --> Deleted : retention elapses
    Deleted --> [*]

    note right of Dunning
        Inbound elder calls continue.
        Safeguarding obligations continue.
        CMR-008.1, CMR-008.2.
    end note

    note left of Cancelled
        Cancellation within 14 days of contract
        carries the statutory right under the
        CCRs 2013, and must take no more steps
        than signup. CMR-001, CMR-002.
    end note

stateDiagram-v2
    [*] --> Healthy
    Healthy --> Warning : 75 percent consumed
    Warning --> Healthy : period resets
    Warning --> Exhausted : fully consumed
    Exhausted --> Frozen : releases blocked
    Frozen --> Remediating : remediation change permitted
    Remediating --> Healthy : metric recovers and period resets
    Frozen --> Frozen : non-remediation change rejected

    note right of Frozen
        SAFETY_LOCKED behaviours continue
        unchanged throughout. Exhaustion
        stops change, never protection.
        SFB-011.
    end note

graph TB
    subgraph OWN["Own hardware — no credit spend"]
        PIPE["Pipecat worker"]
        PG[("Postgres in Docker<br/>graph, consent, audit chain")]
        INF["Infisical<br/>Contabo, UK"]
        EVAL["Eval harness"]
        GRAF["Grafana / Tempo"]
    end

    subgraph AWS["AWS — credits"]
        VC["Chime SDK<br/>Voice Connector"]
        TR["Transcribe<br/>streaming"]
        BR["Bedrock<br/>Claude"]
        PO["Polly"]
        S3[("S3 corpus<br/>lifecycle rule set first")]
    end

    PHONE(["UK phone"]) <--> VC
    VC <-->|SIP / RTP| PIPE
    PIPE --> TR
    PIPE --> BR
    PIPE --> PO
    PIPE --> S3
    PIPE --> PG
    INF -.->|"runtime injection"| PIPE
    PIPE --> GRAF
    S3 --> EVAL

graph LR
    subgraph UK["UK / UK-adequate boundary"]
        direction TB
        CARRIER["Carrier"] --> GW["Voice gateway"]
        GW --> WORKER["Voice worker"]
        WORKER --> STT["STT"]
        WORKER --> TTS["TTS"]
        WORKER --> ORCH["Lide orchestrator"]
        ORCH --> AUTHZ["Authorisation"]
        AUTHZ --> DB[("Aurora")]
        ORCH --> LLM["Bedrock<br/>in-region or EU-geo<br/>UNVERIFIED, see AD-03"]
        WORKER --> CLS["Safety classifier"]
    end

    OUT["Anything outside<br/>UK adequacy"]
    UK -.->|"prohibited"| OUT

flowchart LR
    PR["Pull request"] --> SCAN["Secret scanning"]
    SCAN --> UNIT["Unit + integration"]
    UNIT --> BUDGET{"Safety budget<br/>exhausted?"}
    BUDGET -->|"Yes, non-remediation"| BLOCK["Block"]
    BUDGET -->|No| GATE{"Eval gate"}
    GATE -->|"classifier recall below baseline"| BLOCK
    GATE -->|"unsupported claim above zero"| BLOCK
    GATE -->|"digest omission below floor"| BLOCK
    GATE -->|"adversarial suite fails"| BLOCK
    GATE -->|Pass| STAGE["Staging<br/>synthetic data only"]
    STAGE --> APPROVE["Manual approval"]
    APPROVE --> SECRETS{"Secrets service<br/>reachable?"}
    SECRETS -->|No| FAILC["Fail deployment<br/>no env-var fallback"]
    SECRETS -->|Yes| PROD["Production"]

sequenceDiagram
    participant S as Service
    participant I as Infisical UK
    participant A as Audit service

    S->>I: authenticate as machine identity
    Note over I: identity scoped to<br/>one environment only
    I-->>S: short-lived token
    S->>I: fetch secrets for env
    I-->>S: secrets, runtime memory only
    I->>A: access log entry

    alt Leaver
        Note over I: revoke access within 24h
        Note over I: rotate readable secrets within 7d
    end
    alt Exposure detected
        Note over I: rotate within 24h
        I->>A: exposure and rotation recorded
    end

flowchart TD
    NEED(["Engineer needs<br/>production data"]) --> SYN{"Synthetic data<br/>sufficient?"}
    SYN -->|Yes| USE["Use synthetic dataset"]
    SYN -->|No| REQ["Raise break-glass request<br/>with justification"]
    REQ --> APP{"Second<br/>approver?"}
    APP -->|No| DENIED["Denied and logged"]
    APP -->|Yes| GRANT["Time-boxed grant"]
    GRANT --> WORK["Access"]
    WORK --> EXP["Automatic expiry"]
    EXP --> DISC["Disclose to affected<br/>data subject"]
    DISC --> AUD["Audit entry"]

sequenceDiagram
    participant APP as Application
    participant PG as Postgres audit table
    participant J as Verification job
    participant S3 as S3 Object Lock

    APP->>PG: append entry
    Note over PG: hash chained to previous entry<br/>UPDATE and DELETE denied to all roles
    loop Daily
        J->>PG: walk chain
        J->>S3: write Merkle root, compliance mode
        J->>J: compare against anchored roots
        alt Mismatch
            J->>APP: alert within 5 minutes
        end
    end

flowchart TD
    B["Scheduled backup<br/>RPO 15 min"] --> ENC["Encrypted, UK region"]
    ENC --> STORE[("Backup store")]
    STORE --> TEST["Quarterly restore test"]
    TEST --> VERIFY["Verify audit chain<br/>before return to service"]

    ER(["Erasure request"]) --> DEL["Delete from live stores<br/>within 1 month"]
    DEL --> CALC["Calculate backup cycle<br/>for expunge"]
    CALC --> TELL["Confirm expunge date<br/>to the subject"]
    CALC --> EXP["Expunge on cycle"]

sequenceDiagram
    autonumber
    participant C as Carer
    participant APP as Carer surface
    participant ONB as Onboarding service
    participant O as Omi
    participant E as Elder

    C->>APP: sign up
    APP->>ONB: verify carer contact
    C->>APP: enter elder number
    APP->>C: declare relationship and basis
    ONB->>ONB: check number not registered elsewhere
    alt Already registered
        ONB-->>C: block activation, raise review
    end
    ONB->>C: written statement of what mum will be told
    ONB->>ONB: verify number reachable
    ONB->>O: schedule first call
    O->>E: disclosure, recording notice, consent script
    alt Consent given
        E-->>O: yes
        ONB->>ONB: activate
        ONB-->>C: active
    else Declined or capacity unclear
        ONB-->>C: not activated, no content disclosed
    end

flowchart TD
    REQ(["person, verb, domain, resource"]) --> EXCL{"Exclusion edge<br/>present?"}
    EXCL -->|Yes| DENYX["Deny, unconditional"]
    EXCL -->|No| ROLE{"Role grants<br/>this verb?"}
    ROLE -->|No| DENYR["Deny, default"]
    ROLE -->|Yes| TIME{"Grant within<br/>valid window?"}
    TIME -->|No| DENYT["Deny, expired"]
    TIME -->|Yes| SCOPE{"Domain in<br/>permission scope?"}
    SCOPE -->|No| DENYS["Deny"]
    SCOPE -->|Yes| ALLOW["Allow"]
    ALLOW --> LOG["Audit entry"]
    DENYX --> LOG
    DENYR --> LOG
    DENYT --> LOG
    DENYS --> LOG

flowchart TD
    D(["Detection"]) --> T{"Type?"}
    T -->|"Personal data breach"| PD["Assess risk to subjects"]
    PD --> ICO{"Reportable?"}
    ICO -->|Yes| REP["ICO notification record<br/>within 72h of detection"]
    ICO -->|No| RECN["Record decision and reasoning"]
    REP --> SUBJ{"High risk<br/>to subjects?"}
    SUBJ -->|Yes| TELL["Notify affected subjects"]
    SUBJ -->|No| PIR
    TELL --> PIR
    RECN --> PIR

    T -->|"Safeguarding incident"| SG["Clinical lead leads"]
    SG --> EXT{"External referral<br/>needed?"}
    EXT -->|Yes| LA["Local authority /<br/>Action Fraud / bank"]
    EXT -->|No| PIR
    LA --> PIR["Post-incident review"]

    T -->|"Secret exposure"| SECX["Rotate within 24h"]
    SECX --> AUDIT["Record in audit"]
    AUDIT --> PIR

sequenceDiagram
    autonumber
    participant E as Eval harness
    participant B as Safety budget service
    participant P as Pipeline
    participant CL as Clinical lead
    participant OC as On-call engineer

    E->>B: metric result per release and production sample
    B->>B: consume budget
    alt 75 percent consumed
        B->>CL: alert
        B->>OC: alert
    else Exhausted
        B->>CL: notify within 1 hour
        B->>P: freeze releases to subsystem
        P-->>P: reject non-remediation changes
        Note over B: SAFETY_LOCKED behaviours<br/>continue unchanged
    end
    CL->>B: approve any budget change, with rationale
    B->>B: record actor, before, after, rationale