# The structured half of docs/capabilities/invariants.md. HAND-WRITTEN.
#
# The prose, the evidence and the reasoning live in the .md. This file carries
# only what a machine needs: the mark, which capabilities the rule touches, and
# which components participate in it. build_ledger.py checks the two agree, so
# an invariant cannot exist in one and not the other.
#
# mark: explicit | implied | unresolved. `split` means the rule is written down
# in one half and not in the other, and the .md says which half is which.

invariants:
  - id: 1
    title: Continuity across turns and across reaches
    mark: implied
    question: Is a conversation per reach, or one conversation the reaches are windows onto?
    capabilities: [web-ui, voice, telegram, ask-instead-of-guessing]
    components: [state.dialogue_sessions, state.clarify_store, proc.mavweb, core.voice_server, core.sink_telegram]

  - id: 2
    title: Memory and correction semantics
    mark: explicit
    split: true
    capabilities: [facts, notes, recall]
    components: [state.facts, state.notes, state.memory_vectors, core.recall, router.embedder, core.q.factbykey, core.fact_enrichment, core.netscan]

  - id: 3
    title: Current context and presence
    mark: explicit
    capabilities: [interruption-policy, calendar-management, morning-routine]
    components: [state.presence_state, core.gatherer, core.q.calendar, proc.mavcaldav, core.dispatcher]

  - id: 4
    title: Proactive attention
    mark: explicit
    capabilities: [interruption-policy, digest-of-held-nudges, routine-proposals, praxis]
    components: [core.tick_loop, core.rules, state.digest_entries, state.nudges, core.q.attention, ext.praxis]

  - id: 5
    title: Interruption policy
    mark: explicit
    split: true
    question: Does a held nudge have a shelf life?
    capabilities: [interruption-policy, digest-of-held-nudges, telegram, ntfy]
    components: [core.dispatcher, state.delivery_attempts, state.digest_entries, core.rules, core.sink_telegram, core.sink_ntfy, core.sink_voice]

  - id: 6
    title: Clarification and follow-up ownership
    mark: implied
    capabilities: [ask-instead-of-guessing, route-an-utterance]
    components: [core.preroute, state.clarify_store, state.dialogue_sessions, core.turn_route]

  - id: 7
    title: Degradation and honesty
    mark: explicit
    split: true
    question: At what depth of fallback does silence stop being honest?
    capabilities: [answer-from-the-world, speech-to-text, route-an-utterance, speak-as-herself, read-an-encyclopedia, weather]
    components: [core.model_seam, core.stt_seam, router.cascade, router.classifier, core.query_chain, core.phraser, core.q.kiwix, core.q.general]

  - id: 8
    title: Authority and confirmation
    mark: unresolved
    question: Where is the one point that decides whether this origin may perform this effect with this evidence?
    capabilities: [hexis, praxis, voice, passkey-and-step-up, encrypted-database]
    components: [core.auth_gate, core.risk_policy, state.pending_act, state.tools, core.action_act, core.ecosystem_hexis_gate, core.praxis_acts, core.voice_server, bnd.voice_tcp, core.daemon_lock]

  - id: 9
    title: Privacy boundaries
    mark: explicit
    capabilities: [answer-from-the-world, answer-from-your-own-data, recall, read-an-encyclopedia]
    components: [core.q.personal, core.query_chain, core.q.search, core.q.kiwix, bnd.http_ecosystem]

  - id: 10
    title: Learning from outcomes
    mark: unresolved
    question: Is behavioural learning wanted, or is the negative criterion the whole of the intent?
    capabilities: [learning-the-style, learning-from-mistakes, interruption-policy, route-an-utterance]
    components: [state.nudges, state.routing_labels, core.tick_loop, core.rules]

  - id: 11
    title: Capability composition
    mark: implied
    question: What is the single unit that competes for a turn?
    capabilities: [command-chaining, route-an-utterance, answer-from-your-own-data, ask-instead-of-guessing]
    components: [core.action_table, core.query_chain, core.preroute, router.cascade, router.stage0, router.claim, router.modes]

  - id: 12
    title: Persistence across restart
    mark: implied
    capabilities: [ask-instead-of-guessing, praxis, route-an-utterance]
    components: [state.dialogue_sessions, state.clarify_store, state.decision_ring, state.routing_traces, state.tick_memo, state.surfaced_items]