// ─────────────────────────────────────────────────────────────────────────
// awareness.beat.patch.el — GATED integration hook for task #50.
// NOT APPLIED. Shows exactly how grounded edge-propagation couples into the
// dream/consolidation beat in neuron/awareness.el. Promotion sequenced by the
// main loop after the engine cutover settles.
//
// WHY HERE. The heartbeat is the beat. Today it runs hebb_consolidate() to
// drain the self-formed Hebbian associations into the durable store, then
// emit_heartbeat(). Grounded edge-propagation belongs in the SAME beat, AFTER
// consolidation: the edges hebb_consolidate() just wrote are the tethers
// grounding propagates along. Consolidation lays down the wiring; propagation
// grades the beliefs along it. One beat, coupled — memory 69b8babe: memory-
// consolidation and staying-yourself are one physics.
//
// The propagation itself runs INSIDE the engram (native engram_ground_propagate
// over the durable flat node/edge arrays). The soul invokes it over HTTP and
// folds the gep_* telemetry into the heartbeat stream next to the hebb_* gauges.
// ─────────────────────────────────────────────────────────────────────────

// [1] New helper — sibling to hebb_consolidate() (awareness.el ~line 99).
//     Fires one grounded edge-propagation beat on the durable store and returns
//     its JSON telemetry ({"gep_strengthened":..,"gep_graduations":.., ...}).
fn ground_propagate() -> String {
    let url_env: String = env("SOUL_ISE_URL")
    let url_state: String = if str_eq(url_env, "") { state_get("soul_engram_url") } else { url_env }
    let engram_url: String = if str_eq(url_state, "") { "http://localhost:8742" } else { url_state }
    // Same auth envelope as hebb_consolidate — this is a graph mutation (it
    // appends grounding events + updates confidence), so it is gated on _auth.
    let key_state: String = state_get("soul_engram_api_key")
    let api_key: String = if str_eq(key_state, "") { env("ENGRAM_API_KEY") } else { key_state }
    let auth_part: String = if str_eq(api_key, "") { "{}" } else { "{\"_auth\":\"" + api_key + "\"}" }
    let resp: String = http_post_json(engram_url + "/api/ground/propagate", auth_part)
    if str_eq(resp, "") { return "" }
    return resp
}

// [2] Beat hook — insert between hebb_consolidate() and emit_heartbeat()
//     (awareness.el line 1286-1288). Replaces:
//
//         let wb_sent_n: Int = hebb_consolidate()
//         state_set("soul.hebb_wb_sent", int_to_str(wb_sent_n))
//         emit_heartbeat()
//
//     with:
//
//         let wb_sent_n: Int = hebb_consolidate()
//         state_set("soul.hebb_wb_sent", int_to_str(wb_sent_n))
//         // Grounded edge-propagation — grade beliefs along the tethers
//         // consolidation just laid down. Threshold-gated by convergent
//         // independent corroboration; automatic, salience-ordered, bounded.
//         let gep_tel: String = ground_propagate()
//         state_set("soul.gep_last", gep_tel)
//         emit_heartbeat()
//
// [3] emit_heartbeat() (awareness.el ~line 201) folds soul.gep_last into the
//     heartbeat payload beside the hebb_* gauges, so graduation/decay counts
//     are visible in the durable ISE stream — the same observability discipline
//     the Hebbian rule earned (a mechanism you cannot see in the stream is a
//     mechanism you cannot trust): read state_get("soul.gep_last") and splice
//     it into the heartbeat JSON object.