aether-colony 5.3.2 → 5.4.0

package/.aether/utils/curation-ants/nurse.sh

@@ -0,0 +1,153 @@
+#!/bin/bash
+# Nurse curation ant — trust recalculation for observations and instincts
+# Provides: _curation_nurse
+#
+# These functions are sourced by aether-utils.sh at startup.
+# All shared infrastructure (json_ok, json_err, atomic_write,
+# COLONY_DATA_DIR, SCRIPT_DIR, error constants) is available.
+#
+# Subcommand: curation-nurse [--dry-run]
+# Recalculates trust scores for all observations (that have source_type/evidence_type)
+# and applies trust-decay to instincts based on days since created_at.
+
+# ============================================================================
+# _curation_nurse
+# Recalculate trust scores across observations and instincts.
+#
+# Usage: curation-nurse [--dry-run]
+#
+# Output: {observations_updated: N, instincts_updated: N, dry_run: bool}
+# ============================================================================
+_curation_nurse() {
+    local dry_run="false"
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --dry-run) dry_run="true"; shift ;;
+            *) shift ;;
+        esac
+    done
+
+    local obs_updated=0
+    local inst_updated=0
+    local obs_file="$COLONY_DATA_DIR/learning-observations.json"
+    local inst_file="$COLONY_DATA_DIR/instincts.json"
+    local now_epoch
+    now_epoch=$(date -u +%s)
+
+    # ── Recalculate observation trust scores ──────────────────────────────────
+    if [[ -f "$obs_file" ]]; then
+        local obs_count
+        obs_count=$(jq '[.observations[] | select(.source_type != null and .evidence_type != null)] | length' "$obs_file" 2>/dev/null || echo 0)
+
+        if [[ "$obs_count" -gt 0 ]]; then
+            local updated_obs
+            updated_obs=$(jq -c '[.observations[]]' "$obs_file" 2>/dev/null || echo "[]")
+
+            local new_obs_array="[]"
+            while IFS= read -r obs_json; do
+                local source_type evidence_type last_seen
+                source_type=$(echo "$obs_json" | jq -r '.source_type // empty')
+                evidence_type=$(echo "$obs_json" | jq -r '.evidence_type // empty')
+                last_seen=$(echo "$obs_json" | jq -r '.last_seen // empty')
+
+                if [[ -z "$source_type" || -z "$evidence_type" ]]; then
+                    new_obs_array=$(echo "$new_obs_array" | jq --argjson entry "$obs_json" '. += [$entry]')
+                    continue
+                fi
+
+                local days_since=0
+                if [[ -n "$last_seen" ]]; then
+                    local last_epoch
+                    last_epoch=$(date -u -d "$last_seen" +%s 2>/dev/null || date -u -j -f "%Y-%m-%dT%H:%M:%SZ" "$last_seen" +%s 2>/dev/null || echo "$now_epoch")
+                    days_since=$(( (now_epoch - last_epoch) / 86400 ))
+                    [[ "$days_since" -lt 0 ]] && days_since=0
+                fi
+
+                local trust_result trust_score trust_tier
+                trust_result=$(_trust_calculate --source "$source_type" --evidence "$evidence_type" --days-since "$days_since" 2>/dev/null) || true
+                if echo "$trust_result" | jq -e '.ok == true' >/dev/null 2>&1; then
+                    trust_score=$(echo "$trust_result" | jq -r '.result.score')
+                    trust_tier=$(echo "$trust_result" | jq -r '.result.tier')
+                    local updated_entry
+                    updated_entry=$(echo "$obs_json" | jq \
+                        --argjson score "$trust_score" \
+                        --arg tier "$trust_tier" \
+                        '. + {trust_score: $score, trust_tier: $tier}')
+                    new_obs_array=$(echo "$new_obs_array" | jq --argjson entry "$updated_entry" '. += [$entry]')
+                    obs_updated=$((obs_updated + 1))
+                else
+                    new_obs_array=$(echo "$new_obs_array" | jq --argjson entry "$obs_json" '. += [$entry]')
+                fi
+            done < <(echo "$updated_obs" | jq -c '.[]')
+
+            if [[ "$dry_run" != "true" ]]; then
+                local final_obs
+                final_obs=$(jq --argjson obs "$new_obs_array" '.observations = $obs' "$obs_file" 2>/dev/null) || true
+                [[ -n "$final_obs" ]] && atomic_write "$obs_file" "$final_obs"
+            fi
+        fi
+    fi
+
+    # ── Apply trust-decay to instincts ────────────────────────────────────────
+    if [[ -f "$inst_file" ]]; then
+        local active_count
+        active_count=$(jq '[.instincts[] | select(.archived == false)] | length' "$inst_file" 2>/dev/null || echo 0)
+
+        if [[ "$active_count" -gt 0 ]]; then
+            local updated_inst_array="[]"
+            local all_inst
+            all_inst=$(jq -c '[.instincts[]]' "$inst_file" 2>/dev/null || echo "[]")
+
+            while IFS= read -r inst_json; do
+                local archived
+                archived=$(echo "$inst_json" | jq -r '.archived // false')
+
+                if [[ "$archived" == "true" ]]; then
+                    updated_inst_array=$(echo "$updated_inst_array" | jq --argjson entry "$inst_json" '. += [$entry]')
+                    continue
+                fi
+
+                local created_at days_inst=0
+                created_at=$(echo "$inst_json" | jq -r '.provenance.created_at // empty')
+                if [[ -n "$created_at" ]]; then
+                    local created_epoch
+                    created_epoch=$(date -u -d "$created_at" +%s 2>/dev/null || date -u -j -f "%Y-%m-%dT%H:%M:%SZ" "$created_at" +%s 2>/dev/null || echo "$now_epoch")
+                    days_inst=$(( (now_epoch - created_epoch) / 86400 ))
+                    [[ "$days_inst" -lt 0 ]] && days_inst=0
+                fi
+
+                local current_score
+                current_score=$(echo "$inst_json" | jq -r '.trust_score // 0.5')
+                local decay_result decayed_score new_tier
+                decay_result=$(_trust_decay --score "$current_score" --days "$days_inst" 2>/dev/null) || true
+
+                if echo "$decay_result" | jq -e '.ok == true' >/dev/null 2>&1; then
+                    decayed_score=$(echo "$decay_result" | jq -r '.result.decayed')
+                    new_tier=$(_trust_score_to_tier "$decayed_score" 2>/dev/null || echo "dormant")
+                    local updated_entry
+                    updated_entry=$(echo "$inst_json" | jq \
+                        --argjson score "$decayed_score" \
+                        --arg tier "$new_tier" \
+                        '.trust_score = $score | .trust_tier = $tier')
+                    updated_inst_array=$(echo "$updated_inst_array" | jq --argjson entry "$updated_entry" '. += [$entry]')
+                    inst_updated=$((inst_updated + 1))
+                else
+                    updated_inst_array=$(echo "$updated_inst_array" | jq --argjson entry "$inst_json" '. += [$entry]')
+                fi
+            done < <(echo "$all_inst" | jq -c '.[]')
+
+            if [[ "$dry_run" != "true" ]]; then
+                local final_inst
+                final_inst=$(jq --argjson insts "$updated_inst_array" '.instincts = $insts' "$inst_file" 2>/dev/null) || true
+                [[ -n "$final_inst" ]] && atomic_write "$inst_file" "$final_inst"
+            fi
+        fi
+    fi
+
+    json_ok "$(jq -n \
+        --argjson obs "$obs_updated" \
+        --argjson inst "$inst_updated" \
+        --argjson dry "$([ "$dry_run" == "true" ] && echo true || echo false)" \
+        '{observations_updated: $obs, instincts_updated: $inst, dry_run: $dry}')"
+}

package/.aether/utils/curation-ants/orchestrator.sh

@@ -0,0 +1,181 @@
+#!/bin/bash
+# Curation Orchestrator — runs all 8 curation ants in sequence
+# Provides: _curation_run
+#
+# These functions are sourced by aether-utils.sh at startup.
+# All shared infrastructure (json_ok, json_err, COLONY_DATA_DIR, DATA_DIR,
+# error constants) is available when sourced.
+
+# ============================================================================
+# _curation_run
+# Run all 8 curation ants in the correct order.
+#
+# Usage: curation-run [--dry-run] [--verbose]
+#
+# Execution order:
+#   1. sentinel   — health check (abort if corrupt)
+#   2. nurse      — recalculate trust scores
+#   3. critic     — detect contradictions
+#   4. herald     — promote high-trust to QUEEN.md
+#   5. janitor    — clean expired events/archives
+#   6. archivist  — archive low-trust instincts
+#   7. librarian  — inventory stats
+#   8. scribe     — generate report
+#
+# Output: json_ok with {steps, total_steps, succeeded, failed, dry_run,
+#                        report_path, duration_ms}
+# ============================================================================
+_curation_run() {
+    local dry_run="false"
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --dry-run)  dry_run="true";  shift ;;
+            --verbose)  shift ;;
+            *)          shift ;;
+        esac
+    done
+
+    # Portable millisecond timer: try python3, fall back to seconds*1000
+    local start_ms
+    start_ms=$(python3 -c "import time; print(int(time.time()*1000))" 2>/dev/null \
+               || echo $(( $(date +%s) * 1000 )))
+
+    local steps_json="[]"
+    local succeeded=0
+    local failed=0
+    local report_path="null"
+    # Shared variable: holds the raw JSON result of the last step executed
+    local _CR_LAST_RESULT=""
+
+    # _cr_step <name> [extra_args...]
+    # Runs curation-<name> (with --dry-run if set), updates steps_json,
+    # succeeded/failed counters, and sets _CR_LAST_RESULT.
+    # Must be called WITHOUT command substitution so variable mutations persist.
+    _cr_step() {
+        local step_name="$1"
+        shift
+
+        local cmd="curation-${step_name}"
+
+        # Build the args list (avoid empty-array nounset issues)
+        local step_result step_status step_summary
+        if [[ "$dry_run" == "true" && $# -gt 0 ]]; then
+            step_result=$(bash "$0" "$cmd" "--dry-run" "$@" 2>/dev/null) || true
+        elif [[ "$dry_run" == "true" ]]; then
+            step_result=$(bash "$0" "$cmd" "--dry-run" 2>/dev/null) || true
+        elif [[ $# -gt 0 ]]; then
+            step_result=$(bash "$0" "$cmd" "$@" 2>/dev/null) || true
+        else
+            step_result=$(bash "$0" "$cmd" 2>/dev/null) || true
+        fi
+
+        _CR_LAST_RESULT="$step_result"
+
+        if echo "$step_result" | jq -e '.ok == true' >/dev/null 2>&1; then
+            step_status="ok"
+            step_summary=$(echo "$step_result" | jq -r '
+                .result |
+                if type == "object" then
+                    [ to_entries[] | "\(.key) \(.value)" ] | join(", ")
+                else
+                    tostring
+                end
+            ' 2>/dev/null | head -c 120 || echo "ok")
+            [[ -z "$step_summary" ]] && step_summary="ok"
+            succeeded=$(( succeeded + 1 ))
+        else
+            step_status="failed"
+            local err_msg
+            err_msg=$(echo "$step_result" | jq -r '.error // "unknown error"' 2>/dev/null || echo "unknown error")
+            step_summary="$err_msg"
+            failed=$(( failed + 1 ))
+        fi
+
+        steps_json=$(echo "$steps_json" | jq \
+            --arg name "$step_name" \
+            --arg status "$step_status" \
+            --arg summary "$step_summary" \
+            '. += [{"name": $name, "status": $status, "summary": $summary}]')
+    }
+
+    # ── Step 1: Sentinel — health check ─────────────────────────────────────
+    _cr_step "sentinel"
+
+    # Abort remaining steps if sentinel found critical corruption
+    local sentinel_status
+    sentinel_status=$(echo "$steps_json" | jq -r '.[-1].status')
+    if [[ "$sentinel_status" == "ok" ]]; then
+        local corrupt_count
+        corrupt_count=$(echo "$_CR_LAST_RESULT" | jq '[.result.checks[]? | select(.status == "corrupt")] | length' 2>/dev/null || echo 0)
+        if [[ "$corrupt_count" -gt 0 ]]; then
+            for skipped_step in nurse critic herald janitor archivist librarian scribe; do
+                steps_json=$(echo "$steps_json" | jq \
+                    --arg name "$skipped_step" \
+                    '. += [{"name": $name, "status": "skipped", "summary": "skipped: sentinel detected corrupt stores"}]')
+            done
+
+            local end_ms
+            end_ms=$(python3 -c "import time; print(int(time.time()*1000))" 2>/dev/null \
+                     || echo $(( $(date +%s) * 1000 )))
+            local duration_ms=$(( end_ms - start_ms ))
+
+            json_ok "$(jq -n \
+                --argjson steps "$steps_json" \
+                --argjson total 8 \
+                --argjson succeeded "$succeeded" \
+                --argjson failed "$failed" \
+                --argjson dry "$([ "$dry_run" == "true" ] && echo true || echo false)" \
+                --argjson dur "$duration_ms" \
+                '{steps:$steps, total_steps:$total, succeeded:$succeeded, failed:$failed,
+                  dry_run:$dry, report_path:null, duration_ms:$dur}')"
+            return
+        fi
+    fi
+
+    # ── Step 2: Nurse — recalculate trust scores ─────────────────────────────
+    _cr_step "nurse"
+
+    # ── Step 3: Critic — detect contradictions ───────────────────────────────
+    _cr_step "critic"
+
+    # ── Step 4: Herald — promote high-trust to QUEEN.md ─────────────────────
+    _cr_step "herald"
+
+    # ── Step 5: Janitor — clean expired events and archives ──────────────────
+    _cr_step "janitor"
+
+    # ── Step 6: Archivist — archive low-trust instincts ─────────────────────
+    _cr_step "archivist"
+
+    # ── Step 7: Librarian — inventory stats ──────────────────────────────────
+    _cr_step "librarian"
+
+    # ── Step 8: Scribe — generate report ─────────────────────────────────────
+    _cr_step "scribe"
+
+    # Extract report_path from scribe result
+    if echo "$_CR_LAST_RESULT" | jq -e '.ok == true' >/dev/null 2>&1; then
+        local raw_path
+        raw_path=$(echo "$_CR_LAST_RESULT" | jq -r '.result.report_path // empty' 2>/dev/null || echo "")
+        if [[ -n "$raw_path" ]]; then
+            report_path=$(printf '%s' "$raw_path" | jq -Rs '.')
+        fi
+    fi
+
+    local end_ms
+    end_ms=$(python3 -c "import time; print(int(time.time()*1000))" 2>/dev/null \
+             || echo $(( $(date +%s) * 1000 )))
+    local duration_ms=$(( end_ms - start_ms ))
+
+    json_ok "$(jq -n \
+        --argjson steps "$steps_json" \
+        --argjson total 8 \
+        --argjson succeeded "$succeeded" \
+        --argjson failed "$failed" \
+        --argjson dry "$([ "$dry_run" == "true" ] && echo true || echo false)" \
+        --argjson report_path "$report_path" \
+        --argjson dur "$duration_ms" \
+        '{steps:$steps, total_steps:$total, succeeded:$succeeded, failed:$failed,
+          dry_run:$dry, report_path:$report_path, duration_ms:$dur}')"
+}

package/.aether/utils/curation-ants/scribe.sh

@@ -0,0 +1,164 @@
+#!/bin/bash
+# Curation Scribe — Memory Consolidation Report Generation
+# Generates a markdown report of the memory consolidation state.
+#
+# Functions:
+#   _curation_scribe
+#
+# These functions are sourced by aether-utils.sh at startup.
+# All shared infrastructure (json_ok, json_err, COLONY_DATA_DIR, DATA_DIR,
+# error constants) is available when sourced.
+
+# ============================================================================
+# _curation_scribe
+# Generate a markdown report of memory consolidation state.
+# Usage: curation-scribe [--output <path>]
+#
+# Default output: $COLONY_DATA_DIR/curation-report.md
+# Output: json_ok with {report_path:string, sections:N, generated_at:"ISO"}
+# ============================================================================
+_curation_scribe() {
+    local csc_output=""
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --output)
+                csc_output="${2:-}"
+                shift 2
+                ;;
+            *)
+                shift
+                ;;
+        esac
+    done
+
+    local csc_data_dir="${COLONY_DATA_DIR:-${DATA_DIR:-}}"
+    if [[ -z "$csc_data_dir" ]]; then
+        json_err "$E_VALIDATION_FAILED" "curation-scribe: COLONY_DATA_DIR is not set"
+    fi
+
+    [[ -z "$csc_output" ]] && csc_output="$csc_data_dir/curation-report.md"
+
+    local csc_ts
+    csc_ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    local csc_ts_human
+    csc_ts_human=$(date -u +"%Y-%m-%d %H:%M UTC")
+
+    # Step 1: Gather librarian stats (via curation-librarian subcommand if available)
+    local csc_total_instincts=0
+    local csc_active_instincts=0
+    local csc_archived_instincts=0
+    local csc_total_observations=0
+    local csc_total_events=0
+
+    local csc_lib_result
+    if csc_lib_result=$(COLONY_DATA_DIR="$csc_data_dir" DATA_DIR="$csc_data_dir" \
+            bash "$0" curation-librarian 2>/dev/null); then
+        if echo "$csc_lib_result" | jq -e '.ok == true' >/dev/null 2>&1; then
+            csc_total_instincts=$(echo "$csc_lib_result"   | jq '.result.total_instincts   // 0')
+            csc_active_instincts=$(echo "$csc_lib_result"  | jq '.result.active_instincts  // 0')
+            csc_archived_instincts=$(echo "$csc_lib_result"| jq '.result.archived_instincts // 0')
+            csc_total_observations=$(echo "$csc_lib_result"| jq '.result.total_observations // 0')
+            csc_total_events=$(echo "$csc_lib_result"      | jq '.result.total_events       // 0')
+        fi
+    else
+        # Gather stats directly if librarian is not yet available
+        local csc_instincts_file="$csc_data_dir/instincts.json"
+        if [[ -f "$csc_instincts_file" ]] && jq empty "$csc_instincts_file" 2>/dev/null; then
+            csc_total_instincts=$(jq '.instincts | length' "$csc_instincts_file" 2>/dev/null || echo 0)
+            csc_active_instincts=$(jq '[.instincts[] | select(.archived != true)] | length' "$csc_instincts_file" 2>/dev/null || echo 0)
+            csc_archived_instincts=$(jq '[.instincts[] | select(.archived == true)] | length' "$csc_instincts_file" 2>/dev/null || echo 0)
+        fi
+
+        local csc_obs_file="$csc_data_dir/learning-observations.json"
+        if [[ -f "$csc_obs_file" ]] && jq empty "$csc_obs_file" 2>/dev/null; then
+            csc_total_observations=$(jq '.observations | length' "$csc_obs_file" 2>/dev/null || echo 0)
+        fi
+
+        local csc_eb_file="$csc_data_dir/event-bus.jsonl"
+        if [[ -f "$csc_eb_file" ]]; then
+            csc_total_events=$(wc -l < "$csc_eb_file" | tr -d ' ')
+        fi
+    fi
+
+    # Step 2: Gather top 5 trusted instincts
+    local csc_top_instincts=""
+    local csc_instincts_file="$csc_data_dir/instincts.json"
+    if [[ -f "$csc_instincts_file" ]] && jq empty "$csc_instincts_file" 2>/dev/null; then
+        csc_top_instincts=$(jq -r \
+            '[.instincts[] | select(.archived != true)] | sort_by(-.trust_score // -.confidence // 0) | .[0:5][] |
+             "- **[\(.trust_score // .confidence // 0 | . * 100 | floor)%]** \(.trigger // "unknown trigger")"' \
+            "$csc_instincts_file" 2>/dev/null || echo "")
+    fi
+    [[ -z "$csc_top_instincts" ]] && csc_top_instincts="_No instincts found._"
+
+    # Step 3: Gather recent events (last 10)
+    local csc_recent_events=""
+    local csc_eb_file="$csc_data_dir/event-bus.jsonl"
+    if [[ -f "$csc_eb_file" ]] && [[ -s "$csc_eb_file" ]]; then
+        csc_recent_events=$(tail -10 "$csc_eb_file" | \
+            jq -r '"- [\(.timestamp // "?")] **\(.topic // "unknown")**: \(.source // "system")"' \
+            2>/dev/null || echo "")
+    fi
+    [[ -z "$csc_recent_events" ]] && csc_recent_events="_No recent events._"
+
+    # Step 4: Generate recommendations
+    local csc_recommendations=""
+    if [[ "$csc_active_instincts" -gt 40 ]]; then
+        csc_recommendations+="- Run \`curation-archivist\` to archive low-trust instincts (capacity at ${csc_active_instincts}/50)."$'\n'
+    fi
+    if [[ "$csc_total_events" -gt 100 ]]; then
+        csc_recommendations+="- Run \`curation-janitor\` to clean up expired events (${csc_total_events} events on bus)."$'\n'
+    fi
+    if [[ "$csc_total_observations" -gt 200 ]]; then
+        csc_recommendations+="- Consider pruning stale learning observations (${csc_total_observations} total)."$'\n'
+    fi
+    [[ -z "$csc_recommendations" ]] && csc_recommendations="_Memory stores are healthy. No immediate action needed._"
+
+    # Step 5: Write report
+    mkdir -p "$(dirname "$csc_output")"
+
+    cat > "$csc_output" <<REPORT
+# Memory Consolidation Report
+
+_Generated: ${csc_ts_human}_
+
+---
+
+## Memory Health Summary
+
+| Store | Count |
+|-------|-------|
+| Total instincts | ${csc_total_instincts} |
+| Active instincts | ${csc_active_instincts} |
+| Archived instincts | ${csc_archived_instincts} |
+| Learning observations | ${csc_total_observations} |
+| Events on bus | ${csc_total_events} |
+
+---
+
+## Top Trusted Instincts
+
+${csc_top_instincts}
+
+---
+
+## Recent Events
+
+${csc_recent_events}
+
+---
+
+## Recommendations
+
+${csc_recommendations}
+REPORT
+
+    local csc_sections=4
+
+    json_ok "$(jq -nc \
+        --arg report_path "$csc_output" \
+        --argjson sections "$csc_sections" \
+        --arg generated_at "$csc_ts" \
+        '{report_path:$report_path, sections:$sections, generated_at:$generated_at}')"
+}

package/.aether/utils/curation-ants/sentinel.sh

@@ -0,0 +1,119 @@
+#!/bin/bash
+# Curation Sentinel — Memory Health Monitoring
+# Checks health of all memory stores and reports issues.
+#
+# Functions:
+#   _curation_sentinel
+#
+# These functions are sourced by aether-utils.sh at startup.
+# All shared infrastructure (json_ok, json_err, COLONY_DATA_DIR, DATA_DIR,
+# error constants) is available when sourced.
+
+# ============================================================================
+# _curation_sentinel
+# Check health of all memory stores.
+# Usage: curation-sentinel
+#
+# Output: json_ok with {checks:[{store,status,details}], healthy:N, issues:N}
+# ============================================================================
+_curation_sentinel() {
+    local cs_data_dir="${COLONY_DATA_DIR:-${DATA_DIR:-}}"
+    if [[ -z "$cs_data_dir" ]]; then
+        json_err "$E_VALIDATION_FAILED" "curation-sentinel: COLONY_DATA_DIR is not set"
+    fi
+
+    local cs_checks_json="[]"
+    local cs_healthy=0
+    local cs_issues=0
+
+    # Helper: append a check entry
+    # status "healthy" increments healthy; "optional_missing" is neutral;
+    # all other statuses (missing, corrupt, empty) increment issues.
+    _cs_add_check() {
+        local store="$1"
+        local status="$2"
+        local details="$3"
+
+        cs_checks_json=$(echo "$cs_checks_json" | jq \
+            --arg store "$store" \
+            --arg status "$status" \
+            --arg details "$details" \
+            '. += [{store:$store, status:$status, details:$details}]')
+
+        if [[ "$status" == "healthy" ]]; then
+            cs_healthy=$(( cs_healthy + 1 ))
+        elif [[ "$status" != "optional_missing" ]]; then
+            cs_issues=$(( cs_issues + 1 ))
+        fi
+    }
+
+    # Helper: check a JSON file
+    _cs_check_json_file() {
+        local store="$1"
+        local filepath="$2"
+        local required="${3:-false}"
+
+        if [[ ! -f "$filepath" ]]; then
+            if [[ "$required" == "true" ]]; then
+                _cs_add_check "$store" "missing" "Required file not found: $filepath"
+            else
+                _cs_add_check "$store" "optional_missing" "Optional file not found: $filepath"
+            fi
+            return
+        fi
+
+        if [[ ! -s "$filepath" ]]; then
+            _cs_add_check "$store" "empty" "File exists but is empty: $filepath"
+            return
+        fi
+
+        if ! jq empty "$filepath" 2>/dev/null; then
+            _cs_add_check "$store" "corrupt" "File contains invalid JSON: $filepath"
+            return
+        fi
+
+        _cs_add_check "$store" "healthy" "OK"
+    }
+
+    # 1. learning-observations.json
+    _cs_check_json_file "learning-observations" \
+        "$cs_data_dir/learning-observations.json" "false"
+
+    # 2. instincts.json (optional)
+    _cs_check_json_file "instincts" \
+        "$cs_data_dir/instincts.json" "false"
+
+    # 3. instinct-graph.json (optional)
+    _cs_check_json_file "instinct-graph" \
+        "$cs_data_dir/instinct-graph.json" "false"
+
+    # 4. event-bus.jsonl (optional — check last line if exists)
+    local eb_file="$cs_data_dir/event-bus.jsonl"
+    if [[ ! -f "$eb_file" ]]; then
+        _cs_add_check "event-bus" "optional_missing" "Optional file not found: $eb_file"
+    elif [[ ! -s "$eb_file" ]]; then
+        _cs_add_check "event-bus" "healthy" "File is empty (no events)"
+    else
+        local last_line
+        last_line=$(tail -1 "$eb_file")
+        if echo "$last_line" | jq empty 2>/dev/null; then
+            _cs_add_check "event-bus" "healthy" "OK"
+        else
+            _cs_add_check "event-bus" "corrupt" "Last line is not valid JSON"
+        fi
+    fi
+
+    # 5. pheromones.json (required)
+    _cs_check_json_file "pheromones" \
+        "$cs_data_dir/pheromones.json" "true"
+
+    # 6. COLONY_STATE.json (required)
+    _cs_check_json_file "COLONY_STATE" \
+        "$cs_data_dir/COLONY_STATE.json" "true"
+
+    json_ok "$(jq -nc \
+        --argjson checks "$cs_checks_json" \
+        --argjson healthy "$cs_healthy" \
+        --argjson issues "$cs_issues" \
+        '{checks:$checks, healthy:$healthy, issues:$issues}')"
+}