aether-colony 3.1.17 → 5.1.0

package/{runtime → .aether}/utils/watch-spawn-tree.sh

@@ -3,8 +3,17 @@
 # Usage: bash watch-spawn-tree.sh [data_dir]
 
 DATA_DIR="${1:-.aether/data}"
-SPAWN_FILE="$DATA_DIR/spawn-tree.txt"
-VIEW_STATE_FILE="$DATA_DIR/view-state.json"
+# Resolve COLONY_DATA_DIR for per-colony files (standalone script)
+COLONY_DATA_DIR="${COLONY_DATA_DIR:-$DATA_DIR}"
+if [[ -f "$DATA_DIR/COLONY_STATE.json" ]]; then
+  _cn=$(jq -r '.colony_name // empty' "$DATA_DIR/COLONY_STATE.json" 2>/dev/null)
+  if [[ -n "$_cn" ]]; then
+    _cn_safe=$(echo "$_cn" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+    [[ -n "$_cn_safe" ]] && COLONY_DATA_DIR="$DATA_DIR/colonies/$_cn_safe"
+  fi
+fi
+SPAWN_FILE="$COLONY_DATA_DIR/spawn-tree.txt"
+VIEW_STATE_FILE="$COLONY_DATA_DIR/view-state.json"
 
 # ANSI colors
 YELLOW='\033[33m'

package/{runtime → .aether}/utils/xml-compose.sh

@@ -5,14 +5,20 @@
 # Usage: source .aether/utils/xml-compose.sh
 #        xml-compose <input_xml> [output_xml]
 #        xml-compose-worker-priming <priming_xml> [output_xml]
+#        xml-list-includes <xml_file>
 #
 # These functions enable declarative composition of worker configurations
 # using XInclude directives to merge queen-wisdom, active-trails, and stack-profiles.
 
 set -euo pipefail
 
-# Note: This file should be sourced AFTER xml-utils.sh
+# Note: This file should be sourced AFTER xml-utils.sh or xml-core.sh
 # It relies on xml_json_ok, xml_json_err, and XMLLINT_AVAILABLE variables
+# Source xml-core.sh for JSON helpers and tool detection if not already loaded
+if ! type xml_json_ok &>/dev/null; then
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    source "$SCRIPT_DIR/xml-core.sh"
+fi
 
 # ============================================================================
 # Path Validation (Security)
@@ -107,12 +113,12 @@ xml-compose() {
             echo "$composed" > "$output_xml"
             local escaped_output
             escaped_output=$(echo "$output_xml" | jq -Rs '.[:-1]')
-            xml_json_ok "{\"composed\":true,\"output\":$escaped_output,\"sources_resolved\":\"auto\"}"
+            xml_json_ok "$(jq -n --argjson output "$escaped_output" '{composed: true, output: $output, sources_resolved: "auto"}')"
         else
             # Output to stdout wrapped in JSON
             local escaped_composed
             escaped_composed=$(echo "$composed" | jq -Rs '.')
-            xml_json_ok "{\"composed\":true,\"xml\":$escaped_composed,\"sources_resolved\":\"auto\"}"
+            xml_json_ok "$(jq -n --argjson xml "$escaped_composed" '{composed: true, xml: $xml, sources_resolved: "auto"}')"
         fi
         return 0
     fi

package/.aether/utils/xml-convert.sh

@@ -0,0 +1,277 @@
+#!/bin/bash
+# XML Conversion Utilities
+# Bidirectional JSON/XML conversion and document merging
+#
+# Usage: source .aether/utils/xml-convert.sh
+#        xml-to-json <xml_file> [--pretty]
+#        json-to-xml <json_file> [root_element]
+#        xml-merge <output_file> <main_xml_file>
+#        xml-convert-detect-format <file>
+
+set -euo pipefail
+
+# Source xml-core.sh for JSON helpers and tool detection
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/xml-core.sh"
+
+# Additional tool detection for conversion
+XML2JSON_AVAILABLE=false
+if command -v xml2json >/dev/null 2>&1; then
+    XML2JSON_AVAILABLE=true
+fi
+
+# ============================================================================
+# Format Detection
+# ============================================================================
+
+# xml-convert-detect-format: Detect if file is XML or JSON
+# Usage: xml-convert-detect-format <file>
+# Returns: {"ok":true,"result":{"format":"xml|json|unknown","confidence":"high|medium|low"}}
+xml-convert-detect-format() {
+    local file="${1:-}"
+
+    [[ -z "$file" ]] && { xml_json_err "MISSING_ARG" "Missing file argument"; return 1; }
+    [[ -f "$file" ]] || { xml_json_err "FILE_NOT_FOUND" "File not found: $file"; return 1; }
+
+    # Read first 1KB for analysis
+    local header
+    header=$(head -c 1024 "$file" 2>/dev/null || head -c 1024 < "$file")
+
+    # Check for XML signatures
+    if echo "$header" | grep -qE '^\s*<\?xml\s+version'; then
+        xml_json_ok '{"format":"xml","confidence":"high","signature":"xml_declaration"}'
+        return 0
+    fi
+
+    if echo "$header" | grep -qE '^\s*<[a-zA-Z_][a-zA-Z0-9_]*[\s>]'; then
+        xml_json_ok '{"format":"xml","confidence":"medium","signature":"root_element"}'
+        return 0
+    fi
+
+    # Check for JSON signatures
+    if echo "$header" | grep -qE '^\s*(\{|\[)'; then
+        # Verify it's valid JSON
+        if jq empty "$file" 2>/dev/null; then
+            xml_json_ok '{"format":"json","confidence":"high","signature":"valid_json"}'
+            return 0
+        else
+            xml_json_ok '{"format":"json","confidence":"low","signature":"json_like","note":"Invalid JSON syntax"}'
+            return 0
+        fi
+    fi
+
+    xml_json_ok '{"format":"unknown","confidence":"low","signature":"none"}'
+}
+
+# ============================================================================
+# XML to JSON Conversion
+# ============================================================================
+
+# xml-to-json: Convert XML to JSON format
+# Usage: xml-to-json <xml_file> [--pretty]
+# Returns: {"ok":true,"result":{"json":"...","format":"object"}}
+xml-to-json() {
+    local xml_file="${1:-}"
+    local pretty=false
+
+    # Parse optional arguments
+    shift || true
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --pretty) pretty=true; shift ;;
+            *) shift ;;
+        esac
+    done
+
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+
+    # Check well-formedness first
+    local well_formed_result
+    well_formed_result=$(xml-well-formed "$xml_file" 2>/dev/null)
+    if ! echo "$well_formed_result" | jq -e '.result.well_formed' >/dev/null 2>&1; then
+        xml_json_err "PARSE_ERROR" "XML is not well-formed"
+        return 1
+    fi
+
+    # Try xml2json if available (npm package)
+    if [[ "$XML2JSON_AVAILABLE" == "true" ]]; then
+        local json_output
+        if json_output=$(xml2json "$xml_file" 2>/dev/null); then
+            if [[ "$pretty" == "true" ]]; then
+                json_output=$(echo "$json_output" | jq '.')
+            fi
+            local escaped_json
+            escaped_json=$(echo "$json_output" | jq -Rs '.')
+            xml_json_ok "$(jq -n --argjson json "$escaped_json" '{format: "object", json: $json}')"
+            return 0
+        fi
+    fi
+
+    # Fallback: Use xsltproc with built-in XSLT
+    if [[ "$XSLTPROC_AVAILABLE" == "true" ]]; then
+        local xslt_script
+        xslt_script=$(cat << 'XSLT'
+<?xml version="1.0"?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+<xsl:output method="text"/>
+<xsl:template match="/">
+<xsl:text>{"root":</xsl:text>
+<xsl:apply-templates select="*"/>
+<xsl:text>}</xsl:text>
+</xsl:template>
+<xsl:template match="*">
+<xsl:text>{"</xsl:text>
+<xsl:value-of select="name()"/>
+<xsl:text>":</xsl:text>
+<xsl:choose>
+<xsl:when test="count(*) > 0">
+<xsl:text>[</xsl:text>
+<xsl:apply-templates select="*"/>
+<xsl:text>]</xsl:text>
+</xsl:when>
+<xsl:otherwise>
+<xsl:text>"</xsl:text>
+<xsl:value-of select="."/>
+<xsl:text>"</xsl:text>
+</xsl:otherwise>
+</xsl:choose>
+<xsl:text>}</xsl:text>
+<xsl:if test="position() != last()">,</xsl:if>
+</xsl:template>
+</xsl:stylesheet>
+XSLT
+)
+        local json_result
+        json_result=$(echo "$xslt_script" | xsltproc - "$xml_file" 2>/dev/null) || {
+            xml_json_err "CONVERSION_ERROR" "XSLT conversion failed"
+            return 1
+        }
+        local xslt_escaped_json
+        xslt_escaped_json=$(echo "$json_result" | jq -Rs '.')
+        xml_json_ok "$(jq -n --argjson json "$xslt_escaped_json" '{format: "object", json: $json}')"
+        return 0
+    fi
+
+    # Last resort: Use xmlstarlet if available
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
+        local json_result
+        json_result=$(xmlstarlet sel -t -m "/" -o '{"root":{' -m "*" -v "name()" -o ':"' -v "." -o '"' -b -o '}}' "$xml_file" 2>/dev/null) || {
+            xml_json_err "CONVERSION_ERROR" "xmlstarlet conversion failed"
+            return 1
+        }
+        local xmlstar_escaped_json
+        xmlstar_escaped_json=$(echo "$json_result" | jq -Rs '.')
+        xml_json_ok "$(jq -n --argjson json "$xmlstar_escaped_json" '{format: "object", json: $json}')"
+        return 0
+    fi
+
+    xml_json_err "TOOL_NOT_AVAILABLE" "No XML to JSON conversion tool available. Install xml2json, xsltproc, or xmlstarlet."
+    return 1
+}
+
+# ============================================================================
+# JSON to XML Conversion
+# ============================================================================
+
+# json-to-xml: Convert JSON to XML
+# Usage: json-to-xml <json_file> [root_element]
+# Returns: {"ok":true,"result":{"xml":"<root>...</root>"}}
+json-to-xml() {
+    local json_file="${1:-}"
+    local root_element="${2:-root}"
+
+    [[ -z "$json_file" ]] && { xml_json_err "MISSING_ARG" "Missing JSON file argument"; return 1; }
+    [[ -f "$json_file" ]] || { xml_json_err "FILE_NOT_FOUND" "JSON file not found: $json_file"; return 1; }
+
+    # Validate JSON first
+    if ! jq empty "$json_file" 2>/dev/null; then
+        xml_json_err "PARSE_ERROR" "Invalid JSON file: $json_file"
+        return 1
+    fi
+
+    # Build XML using jq to generate structure
+    local xml_output
+    xml_output=$(jq -r --arg root "$root_element" '
+        def to_xml:
+            if type == "object" then
+                to_entries | map(
+                    "<\(.key)>\(.value | to_xml)</\(.key)>"
+                ) | join("")
+            elif type == "array" then
+                map("<item>\(. | to_xml)</item>") | join("")
+            elif type == "string" then
+                .
+            elif type == "number" then
+                tostring
+            elif type == "boolean" then
+                tostring
+            elif type == "null" then
+                ""
+            else
+                tostring
+            end;
+        "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<\($root)>\n" + (to_xml) + "\n</\($root)>"
+    ' "$json_file" 2>/dev/null) || {
+        xml_json_err "CONVERSION_ERROR" "JSON to XML conversion failed"
+        return 1
+    }
+
+    # Escape the XML for JSON output
+    local escaped_xml
+    escaped_xml=$(echo "$xml_output" | jq -Rs '.')
+    xml_json_ok "$(jq -n --argjson xml "$escaped_xml" '{xml: $xml}')"
+}
+
+# ============================================================================
+# XML Document Merging
+# ============================================================================
+
+# xml-merge: XInclude document merging
+# Usage: xml-merge <output_file> <main_xml_file>
+# Returns: {"ok":true,"result":{"merged":true,"output":"<path>","sources_resolved":N}}
+xml-merge() {
+    local output_file="${1:-}"
+    local main_xml="${2:-}"
+
+    [[ -z "$output_file" ]] && { xml_json_err "MISSING_ARG" "Missing output file argument"; return 1; }
+    [[ -z "$main_xml" ]] && { xml_json_err "MISSING_ARG" "Missing main XML file argument"; return 1; }
+    [[ -f "$main_xml" ]] || { xml_json_err "FILE_NOT_FOUND" "Main XML file not found: $main_xml"; return 1; }
+
+    # Check well-formedness of main file
+    local well_formed_result
+    well_formed_result=$(xml-well-formed "$main_xml" 2>/dev/null)
+    if ! echo "$well_formed_result" | jq -e '.result.well_formed' >/dev/null 2>&1; then
+        xml_json_err "PARSE_ERROR" "Main XML file is not well-formed"
+        return 1
+    fi
+
+    # Use xmllint for XInclude processing with security flags
+    if [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        local merged
+        merged=$(xmllint --nonet --noent --xinclude "$main_xml" 2>/dev/null) || {
+            xml_json_err "MERGE_ERROR" "XInclude merge failed"
+            return 1
+        }
+
+        # Write output
+        echo "$merged" > "$output_file"
+
+        # Count resolved includes (approximate)
+        local resolved_count
+        resolved_count=$(echo "$merged" | grep -c '<xi:include' 2>/dev/null || echo "0")
+
+        local escaped_output
+        escaped_output=$(echo "$output_file" | jq -Rs '.[:-1]')
+        xml_json_ok "$(jq -n --argjson output "$escaped_output" --argjson sources_resolved "$resolved_count" '{merged: true, output: $output, sources_resolved: $sources_resolved}')"
+        return 0
+    fi
+
+    # Without xmllint, we cannot safely process XInclude
+    xml_json_err "TOOL_NOT_AVAILABLE" "xmllint required for XInclude merging. Install libxml2 utilities."
+    return 1
+}
+
+# Export functions
+export -f xml-convert-detect-format xml-to-json json-to-xml xml-merge
+export XML2JSON_AVAILABLE

package/{runtime → .aether}/utils/xml-core.sh

@@ -89,10 +89,8 @@ xml-validate() {
         xml_json_ok '{"valid":true,"errors":[]}'
         return 0
     } || {
-        # Escape errors for JSON
-        local escaped_errors
-        escaped_errors=$(echo "$errors" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\t/\\t/g' | tr '\n' ' ')
-        xml_json_ok "{\"valid\":false,\"errors\":[\"$escaped_errors\"]}"
+        # Escape errors for JSON using jq
+        xml_json_ok "$(jq -n --arg errors "$errors" '{valid: false, errors: [$errors]}')"
         return 0
     }
 }
@@ -144,12 +142,10 @@ xml-format() {
 
     if [[ -n "$output_file" ]]; then
         echo "$formatted" > "$output_file"
-        xml_json_ok "{\"formatted\":true,\"path\":\"$output_file\"}"
+        xml_json_ok "$(jq -n --arg path "$output_file" '{formatted: true, path: $path}')"
     else
-        # Escape for JSON
-        local escaped
-        escaped=$(echo "$formatted" | sed 's/\\/\\\\/g; s/"/\\"/g' | tr '\n' ' ')
-        xml_json_ok "{\"formatted\":true,\"output\":\"$escaped\"}"
+        # Escape for JSON using jq
+        xml_json_ok "$(jq -n --arg output "$formatted" '{formatted: true, output: $output}')"
     fi
 }
 

package/.aether/utils/xml-query.sh

@@ -0,0 +1,201 @@
+#!/bin/bash
+# XML Query Utilities
+# XPath queries with xmlstarlet and xmllint fallback
+#
+# Usage: source .aether/utils/xml-query.sh
+#        xml-query <xml_file> <xpath_expression>
+#        xml-query-attr <xml_file> <xpath_expression>
+#        xml-query-text <xml_file> <element_name>
+#        xml-query-count <xml_file> <xpath_expression>
+
+set -euo pipefail
+
+# Source xml-core.sh for JSON helpers and tool detection
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/xml-core.sh"
+
+# ============================================================================
+# XPath Query Functions
+# ============================================================================
+
+# xml-query: Execute XPath query against XML file
+# Usage: xml-query <xml_file> <xpath_expression>
+# Returns: {"ok":true,"result":{"matches":["value1","value2",...]}}
+xml-query() {
+    local xml_file="${1:-}"
+    local xpath="${2:-}"
+
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -z "$xpath" ]] && { xml_json_err "MISSING_ARG" "Missing XPath expression"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+
+    local results=""
+
+    # Prefer xmlstarlet for full XPath support
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
+        results=$(xmlstarlet sel -t -v "$xpath" "$xml_file" 2>/dev/null | tr '\n' '|')
+        # Remove trailing pipe
+        results="${results%|}"
+    elif [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        # xmllint has limited XPath but works for basic queries
+        # Note: xmllint --xpath returns the text content of matched nodes
+        results=$(xmllint --nonet --noent --xpath "$xpath" "$xml_file" 2>/dev/null | \
+                  sed 's/<[^>]*>//g' | tr '\n' '|' | sed 's/|$//')
+    else
+        xml_json_err "TOOL_NOT_AVAILABLE" "No XPath-capable tool available (install xmlstarlet or libxml2)"
+        return 1
+    fi
+
+    # Build JSON array from pipe-separated results
+    if [[ -n "$results" ]]; then
+        local json_array="["
+        local first=true
+        IFS='|' read -ra matches <<< "$results"
+        for match in "${matches[@]}"; do
+            # Trim whitespace and escape for JSON
+            match=$(echo "$match" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+            match=$(echo "$match" | sed 's/\\/\\\\/g; s/"/\\"/g')
+            if [[ "$first" == "true" ]]; then
+                first=false
+                json_array="$json_array\"$match\""
+            else
+                json_array="$json_array,\"$match\""
+            fi
+        done
+        json_array="$json_array]"
+        xml_json_ok "{\"matches\":$json_array}"
+    else
+        xml_json_ok '{"matches":[]}'
+    fi
+}
+
+# xml-query-attr: Extract attribute values using XPath
+# Usage: xml-query-attr <xml_file> <element_xpath> <attribute_name>
+# Returns: {"ok":true,"result":{"attribute":"name","values":["val1","val2"]}}
+xml-query-attr() {
+    local xml_file="${1:-}"
+    local element_xpath="${2:-}"
+    local attr_name="${3:-}"
+
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -z "$element_xpath" ]] && { xml_json_err "MISSING_ARG" "Missing element XPath"; return 1; }
+    [[ -z "$attr_name" ]] && { xml_json_err "MISSING_ARG" "Missing attribute name"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+
+    local full_xpath="${element_xpath}/@${attr_name}"
+    local results=""
+
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
+        results=$(xmlstarlet sel -t -v "$full_xpath" "$xml_file" 2>/dev/null | tr '\n' '|')
+        results="${results%|}"
+    elif [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        # xmllint can extract attributes with //@attrname syntax
+        results=$(xmllint --nonet --noent --xpath "$full_xpath" "$xml_file" 2>/dev/null | tr '\n' '|')
+        results="${results%|}"
+    else
+        xml_json_err "TOOL_NOT_AVAILABLE" "No XPath-capable tool available"
+        return 1
+    fi
+
+    # Build JSON array
+    if [[ -n "$results" ]]; then
+        local json_array="["
+        local first=true
+        IFS='|' read -ra values <<< "$results"
+        for val in "${values[@]}"; do
+            val=$(echo "$val" | sed 's/\\/\\\\/g; s/"/\\"/g')
+            if [[ "$first" == "true" ]]; then
+                first=false
+                json_array="$json_array\"$val\""
+            else
+                json_array="$json_array,\"$val\""
+            fi
+        done
+        json_array="$json_array]"
+        xml_json_ok "$(jq -n --arg attribute "$attr_name" --argjson values "$json_array" '{attribute: $attribute, values: $values}')"
+    else
+        xml_json_ok "$(jq -n --arg attribute "$attr_name" '{attribute: $attribute, values: []}')"
+    fi
+}
+
+# xml-query-text: Extract text content of elements
+# Usage: xml-query-text <xml_file> <element_name>
+# Returns: {"ok":true,"result":{"element":"name","text":["text1","text2"]}}
+xml-query-text() {
+    local xml_file="${1:-}"
+    local element_name="${2:-}"
+
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -z "$element_name" ]] && { xml_json_err "MISSING_ARG" "Missing element name"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+
+    local xpath="//$element_name"
+    local results=""
+
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
+        # Use -m to match nodes and extract text
+        results=$(xmlstarlet sel -t -m "$xpath" -v "." -n "$xml_file" 2>/dev/null | tr '\n' '|')
+        results="${results%|}"
+    elif [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        # xmllint --xpath returns text content directly for simple paths
+        results=$(xmllint --nonet --noent --xpath "$xpath" "$xml_file" 2>/dev/null | \
+                  sed 's/<[^>]*>//g' | tr '\n' '|' | sed 's/|$//')
+    else
+        xml_json_err "TOOL_NOT_AVAILABLE" "No XPath-capable tool available"
+        return 1
+    fi
+
+    if [[ -n "$results" ]]; then
+        local json_array="["
+        local first=true
+        IFS='|' read -ra texts <<< "$results"
+        for text in "${texts[@]}"; do
+            text=$(echo "$text" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+            text=$(echo "$text" | sed 's/\\/\\\\/g; s/"/\\"/g')
+            if [[ "$first" == "true" ]]; then
+                first=false
+                json_array="$json_array\"$text\""
+            else
+                json_array="$json_array,\"$text\""
+            fi
+        done
+        json_array="$json_array]"
+        xml_json_ok "$(jq -n --arg element "$element_name" --argjson text "$json_array" '{element: $element, text: $text}')"
+    else
+        xml_json_ok "$(jq -n --arg element "$element_name" '{element: $element, text: []}')"
+    fi
+}
+
+# xml-query-count: Count nodes matching XPath expression
+# Usage: xml-query-count <xml_file> <xpath_expression>
+# Returns: {"ok":true,"result":{"count":5}}
+xml-query-count() {
+    local xml_file="${1:-}"
+    local xpath="${2:-}"
+
+    [[ -z "$xml_file" ]] && { xml_json_err "MISSING_ARG" "Missing XML file argument"; return 1; }
+    [[ -z "$xpath" ]] && { xml_json_err "MISSING_ARG" "Missing XPath expression"; return 1; }
+    [[ -f "$xml_file" ]] || { xml_json_err "FILE_NOT_FOUND" "XML file not found: $xml_file"; return 1; }
+
+    local count=0
+
+    if [[ "$XMLSTARLET_AVAILABLE" == "true" ]]; then
+        # Use count() XPath function
+        local count_result
+        count_result=$(xmlstarlet sel -t -v "count($xpath)" "$xml_file" 2>/dev/null)
+        count="${count_result:-0}"
+    elif [[ "$XMLLINT_AVAILABLE" == "true" ]]; then
+        # Count matching lines (approximate for simple cases)
+        local matches
+        matches=$(xmllint --nonet --noent --xpath "$xpath" "$xml_file" 2>/dev/null | grep -c '<' || true)
+        count="${matches:-0}"
+    else
+        xml_json_err "TOOL_NOT_AVAILABLE" "No XPath-capable tool available"
+        return 1
+    fi
+
+    xml_json_ok "{\"count\":$count}"
+}
+
+# Export functions
+export -f xml-query xml-query-attr xml-query-text xml-query-count

package/.aether/utils/xml-utils.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+# XML Utilities Loader
+# Sources all XML modules for backward compatibility
+#
+# IMPORTANT: This file is now a loader only. New code should source
+# individual modules directly from .aether/utils/ or .aether/exchange/
+#
+# Usage: source .aether/utils/xml-utils.sh
+#
+# Modules loaded:
+#   - xml-core.sh      : Core operations (validate, format, escape)
+#   - xml-query.sh     : XPath queries
+#   - xml-convert.sh   : JSON/XML conversion
+#   - xml-compose.sh   : XInclude composition
+#   - pheromone-xml.sh : Pheromone exchange
+#   - wisdom-xml.sh    : Queen wisdom exchange
+#   - registry-xml.sh  : Colony registry exchange
+#
+# Deprecated functions (maintained for compatibility):
+#   - pheromone-to-xml()  -> Use xml-pheromone-export()
+#   - pheromone-from-xml() -> Use xml-pheromone-import()
+#   - queen-wisdom-to-xml() -> Use xml-wisdom-export()
+#   - queen-wisdom-from-xml() -> Use xml-wisdom-import()
+
+set -euo pipefail
+
+# Determine script directory for relative sourcing
+# Handle case when sourced interactively (BASH_SOURCE[0] may be empty)
+if [[ -n "${BASH_SOURCE[0]:-}" ]]; then
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+else
+    # Fallback: derive from the sourced script's location
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+fi
+EXCHANGE_DIR="$(cd "$SCRIPT_DIR/../exchange" && pwd)"
+
+# ============================================================================
+# Load Core Modules
+# ============================================================================
+
+# Core utilities (required by other modules)
+source "$SCRIPT_DIR/xml-core.sh"
+
+# Query functions
+source "$SCRIPT_DIR/xml-query.sh"
+
+# Conversion functions
+source "$SCRIPT_DIR/xml-convert.sh"
+
+# Composition functions
+source "$SCRIPT_DIR/xml-compose.sh"
+
+# ============================================================================
+# Load Exchange Modules
+# ============================================================================
+
+# Pheromone exchange (export/import)
+source "$EXCHANGE_DIR/pheromone-xml.sh"
+
+# Queen wisdom exchange
+source "$EXCHANGE_DIR/wisdom-xml.sh"
+
+# Colony registry exchange
+source "$EXCHANGE_DIR/registry-xml.sh"
+
+# ============================================================================
+# Backward Compatibility Aliases
+# ============================================================================
+
+# Map old function names to new ones for compatibility
+pheromone-to-xml() { xml-pheromone-export "$@"; }
+pheromone-from-xml() { xml-pheromone-import "$@"; }
+queen-wisdom-to-xml() { xml-wisdom-export "$@"; }
+queen-wisdom-from-xml() { xml-wisdom-import "$@"; }
+registry-to-xml() { xml-registry-export "$@"; }
+registry-from-xml() { xml-registry-import "$@"; }
+
+# Export compatibility aliases
+export -f pheromone-to-xml pheromone-from-xml
+export -f queen-wisdom-to-xml queen-wisdom-from-xml
+export -f registry-to-xml registry-from-xml
+
+# ============================================================================
+# Module Information
+# ============================================================================
+
+# xml-utils-info: Display module information
+# Usage: xml-utils-info
+xml-utils-info() {
+    xml_json_ok '{
+        "modules": [
+            "xml-core.sh",
+            "xml-query.sh",
+            "xml-convert.sh",
+            "xml-compose.sh",
+            "pheromone-xml.sh",
+            "wisdom-xml.sh",
+            "registry-xml.sh"
+        ],
+        "note": "This loader provides backward compatibility. New code should source individual modules.",
+        "tools": {
+            "xmllint": '"$XMLLINT_AVAILABLE"',
+            "xmlstarlet": '"$XMLSTARLET_AVAILABLE"',
+            "xsltproc": '"$XSLTPROC_AVAILABLE"'
+        }
+    }'
+}
+
+export -f xml-utils-info
+