@drafthq/draft 3.1.5 → 3.2.1

package/scripts/tools/graph-query.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# graph-query.sh — generic read-only escape hatch to the knowledge-graph engine.
+#
+# The highest-leverage single addition (graph-tooling-v2 Phase 2): unlocks all 20
+# edge types and ~30 pre-computed node properties with no new wrapper. Two modes:
+#
+#   --cypher 'MATCH ...'         run arbitrary read-only openCypher (write verbs
+#                                are rejected before the engine ever sees them).
+#   --tool NAME --json '{...}'   passthrough to any read-only engine tool
+#                                (get_code_snippet, search_graph, get_graph_schema,
+#                                trace_path, …). Destructive tools are rejected.
+#
+# Dialect limits (engine v0.8.x — see _graph_queries.sh for the full list):
+#   SAFE   : fixed-length patterns, `=`, `<`, `STARTS WITH`, `NOT x STARTS WITH`,
+#            `AND`, `OR`, rel-type alternation `[:A|B]`, `count(x)`.
+#   UNSAFE : coalesce(), `<>`/`!=`/`<=`/`>=`, NOT EXISTS(...), NOT (pattern),
+#            WITH-grouping aggregation, multi-pattern joins.
+# Passthrough returns the engine's raw error, not a silent empty result.
+#
+# Usage:
+#   scripts/tools/graph-query.sh --repo DIR --cypher 'MATCH (n) RETURN n LIMIT 5'
+#   scripts/tools/graph-query.sh --repo DIR --tool get_graph_schema --json '{}'
+#
+# Output: the raw engine JSON on success; {"source":"unavailable"} (exit 2) when
+# the engine is unavailable. Exit 1 on invocation error / rejected write.
+set -euo pipefail
+
+# shellcheck source=_graph_queries.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_graph_queries.sh"
+
+REPO="."
+CYPHER=""
+TOOL=""
+TOOL_JSON="{}"
+
+usage() {
+    cat <<'EOF'
+graph-query.sh — generic read-only passthrough to the knowledge-graph engine.
+
+Usage:
+  scripts/tools/graph-query.sh --repo DIR --cypher 'MATCH ... RETURN ...'
+  scripts/tools/graph-query.sh --repo DIR --tool NAME [--json '{...}']
+
+Flags:
+  --repo DIR     Repository root (default: cwd).
+  --cypher STR   Read-only openCypher query (write verbs CREATE/MERGE/DELETE/SET/
+                 REMOVE/DROP/DETACH are rejected). The {project} is injected.
+  --tool NAME    Engine tool to call (read-only allowlist). Combine with --json.
+  --json STR     JSON args for --tool (the project is injected if absent).
+  --help         Show this help.
+
+Dialect: avoid coalesce(), <>, NOT EXISTS, NOT(pattern), WITH-aggregation,
+multi-pattern joins. Use =, <, STARTS WITH, AND/OR, [:A|B] alternation.
+
+Output: raw engine JSON on success; {"source":"unavailable"} (exit 2) when the
+engine is unavailable; exit 1 on invocation error or a rejected write verb.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --cypher) CYPHER="$2"; shift 2;;
+        --tool) TOOL="$2"; shift 2;;
+        --json) TOOL_JSON="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+if [[ -n "$CYPHER" && -n "$TOOL" ]]; then
+    echo "ERROR: use either --cypher or --tool, not both" >&2; exit 1
+fi
+if [[ -z "$CYPHER" && -z "$TOOL" ]]; then
+    echo "ERROR: provide --cypher or --tool" >&2; usage >&2; exit 1
+fi
+
+# Read-only allowlist for --tool mode. Destructive/mutating tools are not exposed
+# through this generic hatch (delete_project, index_repository, manage_adr,
+# ingest_traces) — use the purpose-built wrappers, which guard them explicitly.
+TOOL_ALLOW=" get_architecture query_graph trace_path detect_changes get_code_snippet search_graph search_code get_graph_schema index_status list_projects "
+
+if [[ -n "$TOOL" ]]; then
+    [[ "$TOOL_ALLOW" == *" $TOOL "* ]] || {
+        echo "ERROR: tool '$TOOL' is not in the read-only allowlist" >&2
+        echo "Allowed:$TOOL_ALLOW" >&2
+        exit 1
+    }
+fi
+
+# Reject write verbs in --cypher BEFORE the engine sees the query.
+if [[ -n "$CYPHER" ]]; then
+    UPPER="$(printf '%s' "$CYPHER" | tr '[:lower:]' '[:upper:]')"
+    if printf '%s' "$UPPER" | grep -Eqw 'CREATE|MERGE|DELETE|SET|REMOVE|DROP|DETACH'; then
+        echo "ERROR: write verbs are not allowed (read-only passthrough)" >&2
+        exit 1
+    fi
+fi
+
+REPO_ABS="$(cd "$REPO" && pwd)"
+SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+
+unavailable() { echo '{"source":"unavailable"}'; exit 2; }
+
+find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
+command -v jq >/dev/null 2>&1 || unavailable
+
+PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
+[[ -n "$PROJECT" ]] || unavailable
+
+if [[ -n "$CYPHER" ]]; then
+    RES="$(gq_run "$PROJECT" "$CYPHER" || true)"
+    [[ -n "$RES" ]] || unavailable
+    printf '%s\n' "$RES"
+else
+    # Inject the resolved project into the tool args unless the caller set one.
+    echo "$TOOL_JSON" | jq -e . >/dev/null 2>&1 || { echo "ERROR: --json is not valid JSON" >&2; exit 1; }
+    ARGS="$(echo "$TOOL_JSON" | jq -c --arg p "$PROJECT" 'if has("project") then . else . + {project:$p} end')"
+    RES="$(memory_cli "$TOOL" "$ARGS" 2>/dev/null || true)"
+    [[ -n "$RES" ]] || unavailable
+    echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable
+    printf '%s\n' "$RES"
+fi

package/scripts/tools/graph-risk.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# graph-risk.sh — pre-computed risk hotspots from the knowledge graph node props.
+#
+# graph-tooling-v2 Phase 3. The engine already computes per-symbol risk flags
+# (unguarded_recursion, recursion_in_loop, alloc_in_loop, linear_scan_in_loop)
+# during indexing. This wrapper surfaces them so bughunt / deep-review consume the
+# engine's findings instead of re-deriving them by hand.
+#
+# Usage:
+#   scripts/tools/graph-risk.sh --repo DIR [--min-complexity N]
+#
+# Output: JSON {risky:[{symbol, file, complexity, flags:[...]}], total,
+#               truncated, source}. --min-complexity keeps only flagged symbols
+#               whose complexity >= N (filtered client-side; the engine dialect
+#               has no >= operator).
+#
+# Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
+set -euo pipefail
+
+# shellcheck source=_graph_queries.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_graph_queries.sh"
+
+REPO="."
+MIN_COMPLEXITY=0
+
+usage() {
+    cat <<'EOF'
+graph-risk.sh — pre-computed risk hotspots (recursion / in-loop allocations).
+
+Usage:
+  scripts/tools/graph-risk.sh --repo DIR [--min-complexity N]
+
+Flags:
+  --repo DIR           Repository root (default: cwd).
+  --min-complexity N   Keep only flagged symbols with complexity >= N (default 0).
+  --help               Show this help.
+
+Output: JSON {risky:[{symbol, file, complexity, flags}], total, truncated,
+source}. Exit 2 when engine unavailable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --min-complexity) MIN_COMPLEXITY="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+[[ "$MIN_COMPLEXITY" =~ ^[0-9]+$ ]] || { echo "ERROR: --min-complexity must be a non-negative integer" >&2; exit 1; }
+
+REPO_ABS="$(cd "$REPO" && pwd)"
+SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+
+unavailable() { echo '{"risky":[],"total":0,"source":"unavailable"}'; exit 2; }
+
+find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
+command -v jq >/dev/null 2>&1 || unavailable
+
+PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
+[[ -n "$PROJECT" ]] || unavailable
+
+RES="$(gq_run "$PROJECT" "$(gq_q_risk)" || true)"
+[[ -n "$RES" ]] || unavailable
+
+# Columns: symbol, file, complexity, unguarded_recursion, alloc_in_loop,
+# recursion_in_loop, linear_scan_in_loop. complexity arrives as a string.
+echo "$RES" | jq --argjson minc "$MIN_COMPLEXITY" '
+    [ (.rows // [])[]
+      | {symbol:.[0], file:.[1], complexity:((.[2] // "0") | tonumber? // 0),
+         flags: ( [ (if (.[3]|tostring) == "true" then "unguarded_recursion" else empty end),
+                    (if (.[4]|tostring) == "true" then "alloc_in_loop" else empty end),
+                    (if (.[5]|tostring) == "true" then "recursion_in_loop" else empty end),
+                    (if (.[6]|tostring) == "true" then "linear_scan_in_loop" else empty end) ] )}
+      | select(.complexity >= $minc) ] as $r
+    | {risky: $r, total: ($r | length),
+       truncated: (((.rows // []) | length) >= 200),
+       source:"memory-graph"}'

package/scripts/tools/graph-search.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# graph-search.sh — semantic / ranked symbol search over the knowledge graph.
+#
+# Wraps the engine's search_graph (graph-tooling-v2 Phase 3): "find code about X"
+# returns vector/text-ranked symbols, not a literal grep. Use when the user names
+# an intent or concept rather than an exact symbol.
+#
+# Usage:
+#   scripts/tools/graph-search.sh --repo DIR --query "order submission to broker" [--limit N]
+#
+# Output: JSON {query, results:[{name, qualified_name, label, file, start_line,
+#               end_line, rank}], total, source}.
+#
+# Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
+set -euo pipefail
+
+# shellcheck source=_graph_queries.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_graph_queries.sh"
+
+REPO="."
+QUERY=""
+LIMIT=10
+
+usage() {
+    cat <<'EOF'
+graph-search.sh — semantic / ranked symbol search.
+
+Usage:
+  scripts/tools/graph-search.sh --repo DIR --query "STR" [--limit N]
+
+Flags:
+  --repo DIR   Repository root (default: cwd).
+  --query STR  Natural-language or keyword query (required).
+  --limit N    Max results (default: 10).
+  --help       Show this help.
+
+Output: JSON {query, results, total, source}. Exit 2 when engine unavailable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --query) QUERY="$2"; shift 2;;
+        --limit) LIMIT="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+[[ -n "$QUERY" ]] || { echo "ERROR: --query is required" >&2; usage >&2; exit 1; }
+[[ "$LIMIT" =~ ^[0-9]+$ ]] || { echo "ERROR: --limit must be a non-negative integer" >&2; exit 1; }
+
+REPO_ABS="$(cd "$REPO" && pwd)"
+SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+
+unavailable() {
+    jq -n --arg q "$QUERY" '{query:$q, results:[], source:"unavailable"}' 2>/dev/null \
+        || echo '{"results":[],"source":"unavailable"}'
+    exit 2
+}
+
+find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
+command -v jq >/dev/null 2>&1 || unavailable
+
+PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
+[[ -n "$PROJECT" ]] || unavailable
+
+ARGS="$(jq -n --arg p "$PROJECT" --arg q "$QUERY" --argjson n "$LIMIT" \
+    '{project:$p, query:$q, limit:$n}')"
+RES="$(memory_cli search_graph "$ARGS" 2>/dev/null || true)"
+[[ -n "$RES" ]] || unavailable
+echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable
+
+echo "$RES" | jq --arg q "$QUERY" '
+    {query:$q,
+     results: [ (.results // .matches // [])[]
+                | {name:(.name // ""), qualified_name:(.qualified_name // ""),
+                   label:(.label // ""), file:(.file_path // .file // ""),
+                   start_line:(.start_line // null), end_line:(.end_line // null),
+                   rank:(.rank // .score // null)} ],
+     total: ((.results // .matches // []) | length),
+     source:"memory-graph"}'

package/scripts/tools/graph-snapshot.sh

@@ -89,6 +89,16 @@ STATUS_JSON="$(memory_cli index_status "{\"project\":\"$PROJECT\"}" || echo '{}'
 NODES="$(echo "$STATUS_JSON" | jq -r '.nodes // .node_count // .total_nodes // 0' 2>/dev/null || echo 0)"
 EDGES="$(echo "$STATUS_JSON" | jq -r '.edges // .edge_count // .total_edges // 0' 2>/dev/null || echo 0)"
 VER="$("$MEMORY_BIN" --version 2>/dev/null | awk '{print $NF}' || echo unknown)"
+
+# Incremental-refresh provenance (graph-tooling-v2 Phase 5): the engine indexes
+# incrementally (content-based, git-aware), so re-indexing only touches changed
+# files. detect_changes reports that working-tree delta — recorded as provenance
+# and echoed so a refresh shows what moved. Best-effort: never aborts the write.
+CHANGES_JSON="$(memory_cli detect_changes "{\"project\":\"$PROJECT\"}" 2>/dev/null || echo '{}')"
+echo "$CHANGES_JSON" | jq -e . >/dev/null 2>&1 || CHANGES_JSON='{}'
+CHANGED_FILES="$(echo "$CHANGES_JSON" | jq -r '.changed_count // (.changed_files | length?) // 0' 2>/dev/null || echo 0)"
+IMPACTED="$(echo "$CHANGES_JSON" | jq -r '(.impacted_symbols | length?) // 0' 2>/dev/null || echo 0)"
+
 cat > "$OUT/schema.yaml" <<EOF
 # Draft graph gate marker — written by scripts/tools/graph-snapshot.sh
 # Draft is engine-only: this file carries NO graph data. Its presence signals that
@@ -101,8 +111,10 @@ project: "$PROJECT"
 generated_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 indexed_nodes: $NODES
 indexed_edges: $EDGES
+changed_files: $CHANGED_FILES
+impacted_symbols: $IMPACTED
 access: engine-live
 EOF
 
-echo "Indexed $PROJECT and wrote gate marker to $OUT/schema.yaml (nodes=$NODES edges=$EDGES)"
+echo "Indexed $PROJECT and wrote gate marker to $OUT/schema.yaml (nodes=$NODES edges=$EDGES, changed_files=$CHANGED_FILES impacted_symbols=$IMPACTED)"
 exit 0

package/scripts/tools/graph-snippet.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# graph-snippet.sh — verified source + caller/callee counts for a symbol.
+#
+# Wraps the engine's get_code_snippet (graph-tooling-v2 Phase 3). Replaces the
+# grep-then-Read dance with the engine's own attributed source plus its
+# pre-computed caller/callee counts and loop-depth risk signal.
+#
+# Usage:
+#   scripts/tools/graph-snippet.sh --repo DIR --qualified NAME
+#
+# NAME is a fully qualified_name (e.g. pkg.module.Class.method). Use
+# graph-search.sh or `graph-arch.sh | jq` to discover qualified names.
+#
+# Output: JSON {qualified_name, file, start_line, end_line, callers, callees,
+#               transitive_loop_depth, complexity, code, status, source}.
+#   status = "ok" | "no-match" | "unavailable"
+#
+# Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
+set -euo pipefail
+
+# shellcheck source=_graph_queries.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_graph_queries.sh"
+
+REPO="."
+QNAME=""
+
+usage() {
+    cat <<'EOF'
+graph-snippet.sh — verified source + caller/callee counts for a symbol.
+
+Usage:
+  scripts/tools/graph-snippet.sh --repo DIR --qualified NAME
+
+Flags:
+  --repo DIR       Repository root (default: cwd).
+  --qualified NAME Fully qualified symbol name (required).
+  --help           Show this help.
+
+Output: JSON {qualified_name, file, start_line, end_line, callers, callees,
+transitive_loop_depth, complexity, code, status, source}. Exit 2 when engine
+unavailable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --qualified|--symbol) QNAME="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+[[ -n "$QNAME" ]] || { echo "ERROR: --qualified is required" >&2; usage >&2; exit 1; }
+
+REPO_ABS="$(cd "$REPO" && pwd)"
+SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+
+unavailable() {
+    jq -n --arg q "$QNAME" '{qualified_name:$q, status:"unavailable", source:"unavailable"}' 2>/dev/null \
+        || echo '{"status":"unavailable","source":"unavailable"}'
+    exit 2
+}
+
+find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
+command -v jq >/dev/null 2>&1 || unavailable
+
+PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
+[[ -n "$PROJECT" ]] || unavailable
+
+ARGS="$(jq -n --arg p "$PROJECT" --arg q "$QNAME" '{project:$p, qualified_name:$q}')"
+RES="$(memory_cli get_code_snippet "$ARGS" 2>/dev/null || true)"
+[[ -n "$RES" ]] || unavailable
+echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable
+
+# The engine field `source` carries the code text; rename to `code` to avoid
+# colliding with our provenance `source`. no-match when the engine returns an
+# object without a qualified_name/source for the requested symbol.
+echo "$RES" | jq --arg q "$QNAME" '
+    (.qualified_name // .name // null) as $found
+    | {qualified_name: ($found // $q),
+       file: (.file_path // ""),
+       start_line: (.start_line // null),
+       end_line: (.end_line // null),
+       callers: (.callers // null),
+       callees: (.callees // null),
+       transitive_loop_depth: (.transitive_loop_depth // null),
+       complexity: (.complexity // null),
+       code: (.source // ""),
+       status: (if ($found != null or (.source // "") != "") then "ok" else "no-match" end),
+       source: "memory-graph"}'

package/scripts/tools/graph-tests.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# graph-tests.sh — test→symbol coverage from the knowledge graph (TESTS edges).
+#
+# graph-tooling-v2 Phase 3. Two modes:
+#   --symbol NAME  tests that cover a symbol (who tests this?).
+#   --untested     exported symbols with NO TESTS edge (what's untested?).
+#
+# The engine dialect has no anti-join (NOT EXISTS / NOT(pattern) are rejected), so
+# --untested is computed as a set difference in jq: exported symbols minus the
+# set of TESTS targets. Honest about partiality — TESTS coverage depends on the
+# engine resolving test→symbol links, which varies by language/framework.
+#
+# Usage:
+#   scripts/tools/graph-tests.sh --repo DIR --symbol NAME
+#   scripts/tools/graph-tests.sh --repo DIR --untested
+#
+# Output (--symbol):   {symbol, tests:[{test,file}], status, source}
+# Output (--untested): {untested:[{symbol,file}], total, truncated, source}
+#
+# Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
+set -euo pipefail
+
+# shellcheck source=_graph_queries.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_graph_queries.sh"
+
+REPO="."
+SYMBOL=""
+UNTESTED=0
+
+usage() {
+    cat <<'EOF'
+graph-tests.sh — test coverage edges from the knowledge graph.
+
+Usage:
+  scripts/tools/graph-tests.sh --repo DIR --symbol NAME
+  scripts/tools/graph-tests.sh --repo DIR --untested
+
+Flags:
+  --repo DIR     Repository root (default: cwd).
+  --symbol NAME  List tests covering this symbol.
+  --untested     List exported symbols with no TESTS edge.
+  --help         Show this help.
+
+Output: --symbol → {symbol, tests, status, source}; --untested →
+{untested, total, truncated, source}. Exit 2 when engine unavailable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --symbol) SYMBOL="$2"; shift 2;;
+        --untested) UNTESTED=1; shift;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+[[ -n "$SYMBOL" || "$UNTESTED" -eq 1 ]] || { echo "ERROR: provide --symbol or --untested" >&2; usage >&2; exit 1; }
+
+REPO_ABS="$(cd "$REPO" && pwd)"
+SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+
+unavailable() {
+    if [[ "$UNTESTED" -eq 1 ]]; then
+        echo '{"untested":[],"total":0,"source":"unavailable"}'
+    else
+        jq -n --arg s "$SYMBOL" '{symbol:$s, tests:[], status:"unavailable", source:"unavailable"}' 2>/dev/null \
+            || echo '{"tests":[],"status":"unavailable","source":"unavailable"}'
+    fi
+    exit 2
+}
+
+find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
+command -v jq >/dev/null 2>&1 || unavailable
+
+PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
+[[ -n "$PROJECT" ]] || unavailable
+
+if [[ "$UNTESTED" -eq 1 ]]; then
+    EXP="$(gq_run "$PROJECT" "$(gq_q_exported)" || true)"
+    [[ -n "$EXP" ]] || unavailable
+    TST="$(gq_run "$PROJECT" "$(gq_q_tested_all)" || echo '{"rows":[]}')"
+    echo "$TST" | jq -e . >/dev/null 2>&1 || TST='{"rows":[]}'
+    # Pass results via temp files, not argv: the exported set can exceed the
+    # ARG_MAX limit for --argjson on large repos.
+    TMP_EXP="$(mktemp)"; TMP_TST="$(mktemp)"
+    trap 'rm -f "$TMP_EXP" "$TMP_TST"' EXIT
+    printf '%s' "$EXP" > "$TMP_EXP"
+    printf '%s' "$TST" > "$TMP_TST"
+    jq -n --slurpfile exp "$TMP_EXP" --slurpfile tst "$TMP_TST" '
+        ($exp[0] // {}) as $e | ($tst[0] // {}) as $t
+        | ((($t.rows) // []) | map(.[0])) as $tested
+        | [ (($e.rows) // [])[]
+            | select(((.[0]) as $q | $tested | index($q)) | not)
+            | {symbol:.[0], file:.[1]} ] as $u
+        | {untested: $u, total: ($u | length),
+           truncated: (((($e.rows) // []) | length) >= 2000),
+           source:"memory-graph"}'
+    exit 0
+fi
+
+SYM_ESC="$(gq_escape "$SYMBOL")"
+RES="$(gq_run "$PROJECT" "$(gq_q_tests "$SYM_ESC")" || true)"
+[[ -n "$RES" ]] || unavailable
+STATUS="$(gq_symbol_status "$PROJECT" "$SYM_ESC" "$RES")"
+
+echo "$RES" | jq --arg s "$SYMBOL" --arg st "$STATUS" '
+    {symbol:$s,
+     tests: [ (.rows // [])[] | {test:.[0], file:.[1]} ],
+     status:$st, source:"memory-graph"}'

package/scripts/tools/graph-traces.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# graph-traces.sh — fold runtime call traces into the knowledge graph (EXPERIMENTAL).
+#
+# graph-tooling-v2 Phase 6. Wraps the engine's ingest_traces to close the
+# static/dynamic gap — dynamic dispatch the static graph misses (e.g. closures,
+# reflection, virtual calls). This is a WRITE path and is gated behind
+# --experimental. NOTE: in engine v0.8.x ingest_traces is accepted but runtime
+# edge creation is "not yet implemented" — the engine returns its status verbatim.
+#
+# Usage:
+#   scripts/tools/graph-traces.sh ingest --repo DIR --file TRACES.json --experimental
+#
+# TRACES.json is a JSON array of trace records (engine-defined shape).
+#
+# Output: the engine's raw ingest_traces JSON; {"source":"unavailable"} (exit 2)
+# when the engine is unavailable; exit 1 on invocation error or missing
+# --experimental.
+set -euo pipefail
+
+# shellcheck source=_graph_queries.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_graph_queries.sh"
+
+REPO="."
+FILE=""
+ACTION=""
+EXPERIMENTAL=0
+
+usage() {
+    cat <<'EOF'
+graph-traces.sh — fold runtime traces into the graph (EXPERIMENTAL, write path).
+
+Usage:
+  scripts/tools/graph-traces.sh ingest --repo DIR --file TRACES.json --experimental
+
+Flags:
+  ingest          The action (currently the only one).
+  --repo DIR      Repository root (default: cwd).
+  --file PATH     JSON array of trace records (required for ingest).
+  --experimental  Required acknowledgement — this is a write/experimental path.
+  --help          Show this help.
+
+NOTE: engine v0.8.x accepts traces but runtime edge creation is not yet
+implemented; the engine's status is returned verbatim.
+
+Output: raw engine JSON; {"source":"unavailable"} (exit 2) when unavailable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        ingest) ACTION="ingest"; shift;;
+        --repo) REPO="$2"; shift 2;;
+        --file) FILE="$2"; shift 2;;
+        --experimental) EXPERIMENTAL=1; shift;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown argument: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ "$ACTION" == "ingest" ]] || { echo "ERROR: action 'ingest' is required" >&2; usage >&2; exit 1; }
+[[ "$EXPERIMENTAL" -eq 1 ]] || { echo "ERROR: --experimental is required (this writes to the graph)" >&2; exit 1; }
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+[[ -n "$FILE" ]] || { echo "ERROR: --file is required" >&2; usage >&2; exit 1; }
+[[ -f "$FILE" ]] || { echo "ERROR: --file '$FILE' does not exist" >&2; exit 1; }
+
+REPO_ABS="$(cd "$REPO" && pwd)"
+SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+
+unavailable() { echo '{"source":"unavailable"}'; exit 2; }
+
+find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
+command -v jq >/dev/null 2>&1 || unavailable
+
+jq -e . "$FILE" >/dev/null 2>&1 || { echo "ERROR: --file is not valid JSON" >&2; exit 1; }
+
+PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
+[[ -n "$PROJECT" ]] || unavailable
+
+ARGS="$(jq -n --arg p "$PROJECT" --slurpfile t "$FILE" '{project:$p, traces:($t[0])}')"
+RES="$(memory_cli ingest_traces "$ARGS" 2>/dev/null || true)"
+[[ -n "$RES" ]] || unavailable
+echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable
+printf '%s\n' "$RES"