@drafthq/draft 3.7.2 → 5.0.1

package/scripts/tools/_graph_queries.sh

@@ -7,16 +7,20 @@
 # here, not a hunt across N scripts (the Phase 0 :Function bug was duplicated
 # across two files precisely because the Cypher was inlined).
 #
-# Dialect notes (engine v0.8.x, verified live against this engine):
-#   SAFE   : fixed-length patterns, single/multi-hop explicit patterns, `=`, `<`,
-#            `STARTS WITH`, `NOT x STARTS WITH`, `AND`, `OR`, relationship-type
-#            alternation `[:A|B]`, simple `count(x)`.
-#   UNSAFE : coalesce(), `<>` / `!=` / `<=` / `>=`, `NOT EXISTS(...)`,
-#            `NOT (pattern)`, `WITH`-grouping aggregation, multi-pattern joins,
-#            and comparing one property against another (`a.x < b.x` — the
-#            parser wants a literal on the right and fails with "expected value
-#            at pos N"). `<` against a literal is fine.
-#            Every builder below stays inside the SAFE set.
+# Dialect notes (engine v0.9.0, verified live against this engine):
+#   SAFE   : `=`, `<>`/`!=`, `<`, `>`, `<=`, `>=` against a literal; `STARTS WITH`,
+#            `NOT x STARTS WITH`, `AND`, `OR`; explicit and variable-length
+#            patterns (`[:R*1..3]`, fixed depth `[:R*2..2]`); relationship-type
+#            alternation `[:A|B]`; `coalesce()`; `DISTINCT`; `count(x)`,
+#            `count(DISTINCT x)`; `WITH`-grouping aggregation.
+#   UNSAFE : comparing one property against another (`a.x < b.x`, `a.x = b.x` —
+#            the parser wants a literal on the right: "expected value at pos N"),
+#            `NOT EXISTS(...)`, `NOT (pattern)`, path variables (`p=(...)`,
+#            `length(p)`), and multi-pattern joins (`MATCH (a)…, (b)…` parse but
+#            ignore RETURN and LIMIT).
+#   GOTCHA : LIMIT applies before DISTINCT, so `RETURN DISTINCT … LIMIT n` can
+#            return fewer than n rows while more exist — judge truncation on raw
+#            rows. Every builder below stays inside the SAFE set.
 #
 # Label-agnostic on name matches: code units are :Method ⪢ :Function in OO repos;
 # pinning :Function silently returns [] (the graph-tooling-v2 Phase 0 bug). CALLS
@@ -63,7 +67,17 @@ gq_q_inherits_sym()      { printf "MATCH (c)-[:INHERITS]->(p) WHERE c.name='%s'
 gq_q_derived_sym()       { printf "MATCH (c)-[:INHERITS]->(p) WHERE p.name='%s' RETURN c.qualified_name AS child, p.qualified_name AS parent LIMIT 200" "$1"; }
 gq_q_raises()            { printf "MATCH (f {name:'%s'})-[:RAISES|THROWS]->(e) RETURN e.name AS error, e.qualified_name AS qualified LIMIT 200" "$1"; }
 gq_q_raisers()           { printf "MATCH (f)-[:RAISES|THROWS]->(e {name:'%s'}) RETURN f.qualified_name AS raiser, f.file_path AS file LIMIT 200" "$1"; }
-gq_q_node_props()        { printf "MATCH (f) RETURN f.qualified_name AS q, f.complexity AS c, f.cognitive AS cog, f.is_entry_point AS ep LIMIT 10000"; }
+# $1 = comma-separated list of pre-escaped, single-quoted qualified names.
+gq_q_node_props()        { printf "MATCH (f) WHERE f.qualified_name IN [%s] RETURN f.qualified_name AS q, f.complexity AS c, f.cognitive AS cog, f.is_entry_point AS ep LIMIT 1000" "$1"; }
+# Dependents at exactly $2 CALLS hops (one query per depth: path variables are
+# unsupported, so the hop count comes from the fixed depth). Raw rows, no
+# DISTINCT — LIMIT applies before DISTINCT, so only a raw row count at the limit
+# reveals truncation. The file form skips callers inside the target file itself.
+GQ_DEP_LIMIT=5000
+gq_q_dependents_file()   { printf "MATCH (a)-[:CALLS*%s..%s]->(b) WHERE b.file_path = '%s' AND a.file_path <> '%s' RETURN a.qualified_name AS q, a.name AS name, a.file_path AS file, a.is_test AS test LIMIT %s" "$2" "$2" "$1" "$1" "$GQ_DEP_LIMIT"; }
+gq_q_dependents_symbol() { printf "MATCH (a)-[:CALLS*%s..%s]->(b {name:'%s'}) WHERE a.name <> '%s' RETURN a.qualified_name AS q, a.name AS name, a.file_path AS file, a.is_test AS test LIMIT %s" "$2" "$2" "$1" "$1" "$GQ_DEP_LIMIT"; }
+gq_q_importers()         { printf "MATCH (a)-[:IMPORTS]->(b) WHERE b.file_path = '%s' AND a.file_path <> '%s' RETURN a.file_path AS file LIMIT %s" "$1" "$1" "$GQ_DEP_LIMIT"; }
+gq_q_file_exists()       { printf "MATCH (f) WHERE f.file_path = '%s' RETURN f.file_path AS file LIMIT 1" "$1"; }
 gq_q_risk()              { printf "MATCH (f) WHERE f.unguarded_recursion=true OR f.alloc_in_loop=true OR f.recursion_in_loop=true OR f.linear_scan_in_loop=true RETURN f.qualified_name AS symbol, f.file_path AS file, f.complexity AS complexity, f.unguarded_recursion AS unguarded_recursion, f.alloc_in_loop AS alloc_in_loop, f.recursion_in_loop AS recursion_in_loop, f.linear_scan_in_loop AS linear_scan_in_loop LIMIT 200"; }
 
 # ── Runner + classifier ──
@@ -83,7 +97,9 @@ gq_run() {
     payload="$(jq -n --arg p "$project" --arg q "$query" '{project:$p, query:$q}')" || return 3
     res="$(memory_cli query_graph "$payload" 2>/dev/null || true)"
     [[ -n "$res" ]] || return 3
-    printf '%s' "$res" | jq -e . >/dev/null 2>&1 || return 3
+    # Shapeless JSON (`{}`) is not an empty result — it is a failed query.
+    # Callers must not treat it as a measured true-negative.
+    printf '%s' "$res" | jq -e 'has("rows") and (.rows | type == "array")' >/dev/null 2>&1 || return 3
     printf '%s' "$res"
 }
 

package/scripts/tools/_lib.sh

@@ -235,7 +235,7 @@ find_memory_bin() {
 # its own unavailable-JSON shape (the shapes differ per tool).
 graph_bootstrap() {
     local repo="$1" self_repo
-    REPO_ABS="$(cd "$repo" 2>/dev/null && pwd)" || return 1
+    REPO_ABS="$(cd "$repo" 2>/dev/null && pwd -P)" || return 1
     self_repo="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
     find_memory_bin "$REPO_ABS" "$self_repo" || return 1
     command -v jq >/dev/null 2>&1 || return 1
@@ -245,6 +245,8 @@ graph_bootstrap() {
 
 # Run a codebase-memory-mcp CLI tool. Echoes the JSON result (stdout); the engine's
 # `level=...` log lines go to stderr and are discarded unless DRAFT_MEMORY_DEBUG is set.
+# Args travel on stdin: the engine deprecated positional raw JSON (0.9.0 warns it
+# "will be removed in a future release"), and that warning lands in the discarded stderr.
 # Usage: memory_cli <tool> [json-args]
 memory_cli() {
     local tool="$1"
@@ -253,22 +255,12 @@ memory_cli() {
         return 1
     fi
     if [[ -n "${DRAFT_MEMORY_DEBUG:-}" ]]; then
-        "$MEMORY_BIN" cli "$tool" "$args"
+        "$MEMORY_BIN" cli "$tool" <<< "$args"
     else
-        "$MEMORY_BIN" cli "$tool" "$args" 2>/dev/null
+        "$MEMORY_BIN" cli "$tool" <<< "$args" 2>/dev/null
     fi
 }
 
-# Resolve the engine's project name for a repository absolute path via list_projects.
-# Echoes the project name, or nothing if the repo has not been indexed yet.
-memory_project_for_repo() {
-    local repo_abs="$1"
-    command -v jq >/dev/null 2>&1 || return 1
-    memory_cli list_projects '{}' 2>/dev/null \
-        | jq -r --arg p "$repo_abs" '.projects[]? | select(.root_path == $p) | .name' 2>/dev/null \
-        | head -1
-}
-
 # Total physical RAM in MB (portable). Echoes a positive integer, or nothing.
 _total_ram_mb() {
     if [[ -r /proc/meminfo ]]; then
@@ -306,52 +298,69 @@ _can_cgroup_bound() {
 
 # Index a repository under a memory bound. The codebase-memory-mcp engine
 # self-budgets ~50% of *physical* RAM and is not cgroup-aware, so a first index
-# of a huge repo can exhaust the host (the original 30 GB hang). On Linux we
-# confine it to a transient cgroup scope sized to DRAFT_INDEX_MEM_PCT (default
-# 25) of total RAM; CBM_WORKERS caps the engine's parallel working set so the
-# throttle has less transient pressure to absorb. Where cgroup v2 + systemd-run
-# are unavailable (e.g. macOS) the worker cap is the only bound. Never falls back
+# of a huge repo can exhaust the host (the original 30 GB hang). The engine's
+# own budget (CBM_MEM_BUDGET_MB) is set to DRAFT_INDEX_MEM_PCT (default 25) of
+# total RAM unless the user chose one; on Linux the process is also confined to
+# a transient cgroup scope of that size. CBM_WORKERS caps the engine's parallel
+# working set so the throttle has less transient pressure to absorb. Where cgroup
+# v2 + systemd-run are unavailable (e.g. macOS) the budget and worker cap are the
+# bound. Never falls back
 # from a started scope to an unbounded run — a bounded OOM fails the index
 # cleanly (host stays alive) rather than re-triggering the hang.
 # Echoes the engine's JSON result on stdout (same contract as memory_cli).
+# Usage: memory_index_bounded <repo-abs> [project-name]
 memory_index_bounded() {
-    local repo_abs="$1"
+    local repo_abs="$1" name="${2:-}"
     # Payload built with jq (never string concatenation) so a repo path
     # containing a `"` or `\` can never corrupt the JSON sent to the engine.
     command -v jq >/dev/null 2>&1 || return 1
     local json
-    json="$(jq -n --arg r "$repo_abs" '{repo_path:$r}')" || return 1
+    json="$(jq -n --arg r "$repo_abs" --arg n "$name" \
+        '{repo_path:$r} + (if $n == "" then {} else {name:$n} end)')" || return 1
     export CBM_WORKERS="${CBM_WORKERS:-4}"
     local total pct
     total="$(_total_ram_mb)"
     pct="${DRAFT_INDEX_MEM_PCT:-25}"
+    [[ "${total:-0}" -gt 0 ]] && export CBM_MEM_BUDGET_MB="${CBM_MEM_BUDGET_MB:-$(( total * pct / 100 ))}"
     if [[ "${total:-0}" -gt 0 ]] && _can_cgroup_bound; then
         local high_arg max_arg
         read -r high_arg max_arg <<< "$(_mem_bound_args "$total" "$pct")"
         if [[ -n "${DRAFT_MEMORY_DEBUG:-}" ]]; then
             systemd-run --user --scope -q -p "$high_arg" -p "$max_arg" \
-                -- "$MEMORY_BIN" cli index_repository "$json"
+                -- "$MEMORY_BIN" cli index_repository <<< "$json"
         else
             systemd-run --user --scope -q -p "$high_arg" -p "$max_arg" \
-                -- "$MEMORY_BIN" cli index_repository "$json" 2>/dev/null
+                -- "$MEMORY_BIN" cli index_repository <<< "$json" 2>/dev/null
         fi
     else
         memory_cli index_repository "$json"
     fi
 }
 
-# Ensure a repository is indexed in the engine; echo its project name.
-# Indexes on demand when absent. Returns 1 if the engine is unavailable.
+# Bring a repository's engine index up to date; echo its project name.
+# Always re-indexes: the engine indexes incrementally (content-based, git-aware),
+# so an unchanged repo costs ~0.1 s. Indexing only when the project was absent
+# left every live query answering from the first index ever taken — a symbol
+# added since stayed invisible while the result still said status:"ok".
+#
+# The project is named explicitly: the engine derives names by flattening '/' to
+# '-', so /x/a-b/c and /x/a/b-c shared one DB and each index overwrote the other.
+# A repo the engine already knows keeps its name (no forced full re-index); a new
+# one gets <basename>-<sha8 of its path>, which no other path can derive.
+# Returns 1 if the engine is unavailable.
 memory_ensure_index() {
     local repo_abs="$1"
     [[ -n "${MEMORY_BIN:-}" ]] || return 1
     command -v jq >/dev/null 2>&1 || return 1
-    local proj
-    proj="$(memory_project_for_repo "$repo_abs" 2>/dev/null || true)"
-    if [[ -z "$proj" ]]; then
-        proj="$(memory_index_bounded "$repo_abs" \
-            | jq -r '.project // empty' 2>/dev/null || true)"
+    local proj name
+    name="$(memory_cli list_projects '{}' \
+        | jq -r --arg p "$repo_abs" 'first(.projects[]? | select(.root_path == $p) | .name) // empty' 2>/dev/null || true)"
+    if [[ -z "$name" ]]; then
+        name="$(printf '%s' "$repo_abs" | { sha256sum 2>/dev/null || shasum -a 256; } | cut -c1-8)"
+        name="$(basename "$repo_abs")-$name"
     fi
+    proj="$(memory_index_bounded "$repo_abs" "$name" \
+        | jq -r '.project // empty' 2>/dev/null || true)"
     [[ -n "$proj" ]] || return 1
     printf '%s' "$proj"
 }

package/scripts/tools/check-repo-size.sh

@@ -109,7 +109,11 @@ else
         # `head` lets head close the pipe early, which under `pipefail` surfaces
         # sort's SIGPIPE as a hard failure — non-deterministically, depending on
         # whether the output fit in the pipe buffer.
-        largest="$(awk '$4 ~ /^[0-9]+$/ { printf "  %8.2f MB  %s\n", $4 / 1048576, $5 }' <<< "$listing" | sort -rn)"
+        # git ls-tree -l: "mode type sha size<TAB>path" — path may contain spaces.
+        largest="$(awk -F '\t' '$1 ~ / [0-9]+$/ {
+            n = split($1, a, " ")
+            printf "  %8.2f MB  %s\n", a[n] / 1048576, $2
+        }' <<< "$listing" | sort -rn)"
         head -n "$TOP" <<< "$largest"
     fi
 fi

package/scripts/tools/cycle-detect.sh

@@ -64,20 +64,24 @@ graph_bootstrap "$REPO" || unavailable
 # derived from a query that never ran, which is exactly the true-negative
 # confusion Guardrail 4 exists to prevent, and the one failure mode a caller
 # cannot detect. Both queries must land for the sample to mean anything, so
-# either failure routes to `unavailable`. gq_run only ever echoes validated
-# JSON, so nothing downstream needs a second shape guard.
+# either failure routes to `unavailable`. gq_run requires a `.rows` array, so
+# shapeless JSON (`{}`) is unavailable, not an empty sample.
 R2="$(gq_run "$PROJECT" "$(gq_q_cycles2)")" || unavailable
 R3="$(gq_run "$PROJECT" "$(gq_q_cycles3)")" || unavailable
 
-# Self-loops and duplicate orderings are filtered here rather than in Cypher:
-# the engine rejects `a.x < b.x`, which is what the query used to rely on.
-# A 2-cycle comes back twice (A,B and B,A), hence the doubled LIMIT upstream.
+# Degenerate rows and duplicate rotations are filtered here rather than in
+# Cypher: the engine rejects `a.x < b.x`, which is what the query used to rely on.
+# A cycle comes back once per rotation (a 2-cycle as A,B and B,A — hence the
+# doubled LIMIT upstream), and a self-loop also matches both patterns with a
+# repeated node, e.g. (x, x, x). Drop rows that repeat a node, rotate each to
+# start at its smallest member, and keep one of each.
 jq -n --argjson r2 "$R2" --argjson r3 "$R3" '
+    def cycles: map(select((unique | length) == length)
+                    | (indices(min)[0]) as $i | .[$i:] + .[:$i]) | unique;
     ( ((($r2.rows) // []) | length) >= 200
       or ((($r3.rows) // []) | length) >= 100 ) as $trunc
-    | ( ($r2.rows // []) | map(select(.[0] != .[1])) | unique_by(sort) ) as $two
     | {
-        cycles: ($two + ($r3.rows // [])),
+        cycles: ((($r2.rows // []) | cycles) + (($r3.rows // []) | cycles)),
         truncated: $trunc,
         source: "memory-graph"
       }'

package/scripts/tools/graph-callers.sh

@@ -88,7 +88,7 @@ if [[ "$TRANSITIVE" -eq 1 ]]; then
     PAYLOAD="$(jq -n --arg p "$PROJECT" --arg f "$SYMBOL" --argjson d "$DEPTH" \
         '{project:$p, function_name:$f, depth:$d, direction:"both"}')"
     RES="$(memory_cli trace_path "$PAYLOAD" 2>/dev/null || true)"
-    echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable
+    echo "$RES" | jq -e 'has("callers") and (.callers | type == "array")' >/dev/null 2>&1 || unavailable
     N="$(echo "$RES" | jq -r '(.callers // []) | length' 2>/dev/null || echo 0)"
     if [[ "$N" -gt 0 ]]; then STATUS="ok"; else
         STATUS="$(gq_symbol_status "$PROJECT" "$SYM_ESC" '{"rows":[]}')"

package/scripts/tools/graph-impact.sh

@@ -1,24 +1,28 @@
 #!/usr/bin/env bash
 # graph-impact.sh — blast radius for a file or symbol, from the knowledge graph.
 #
-# Replaces `graph --query --file <path> --mode impact`. Backed by the
-# codebase-memory-mcp engine: combines detect_changes (git-diff → impacted
-# symbols, when querying the working tree) with trace_path callers for a named
-# function (transitive upstream dependents).
+# Everything that depends on the target, up to --depth CALLS hops: callers of the
+# symbol, or callers of anything defined in the file plus the files that import
+# it. Callers inside the target file are not downstream and are skipped.
 #
 # Usage:
 #   scripts/tools/graph-impact.sh --repo DIR (--file PATH | --symbol NAME) [--depth N]
 #
-# Output: JSON {target, kind, impacted:[{name,file,qualified,hop}], source}.
-#   `file` is always a path (empty when the engine carries none); the qualified
-#   name has its own field rather than being emitted as if it were a path.
+# Output: JSON {target, kind, impacted:[{name,file,qualified,hop}], downstream_files,
+#   affected_modules, max_depth, by_category:{code,test}, status, truncated, source}.
+#   `impacted` lists each dependent once at its nearest hop, capped at 200; the
+#   aggregates always cover the full set. `truncated` is true when the list was
+#   capped or the engine row limit was hit. A module is a file's top-level path
+#   segment ("." for root files), as in classify-files.sh.
+#   status = ok | no-edges (target known, nothing depends on it) | no-match
+#            (target unknown to the graph)
 #   source = "memory-graph" | "unavailable"
 #
 # Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
 set -euo pipefail
 
-# shellcheck source=_lib.sh
-source "$(dirname "${BASH_SOURCE[0]}")/_lib.sh"
+# shellcheck source=_graph_queries.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_graph_queries.sh"
 
 REPO="."
 FILE=""
@@ -34,12 +38,13 @@ Usage:
 
 Flags:
   --repo DIR     Repository root (default: cwd).
-  --file PATH    Size impact of a changed file (uses git working-tree diff).
-  --symbol NAME  Transitive callers of a function (default depth 3).
-  --depth N      Caller traversal depth for --symbol (default: 3).
+  --file PATH    Dependents of a file (repo-relative, ./-prefixed, or absolute).
+  --symbol NAME  Dependents (transitive callers) of a function.
+  --depth N      Caller traversal depth (default: 3).
   --help         Show this help.
 
-Output: JSON {target, kind, impacted, source}. Exit 2 when engine unavailable.
+Output: JSON {target, kind, impacted, downstream_files, affected_modules,
+max_depth, by_category, status, truncated, source}. Exit 2 when engine unavailable.
 EOF
 }
 
@@ -70,27 +75,50 @@ if [[ -n "$SYMBOL" ]]; then TARGET="$SYMBOL"; KIND="symbol"; else TARGET="$FILE"
 graph_bootstrap "$REPO" || unavailable "$TARGET" "$KIND"
 
 if [[ -n "$SYMBOL" ]]; then
-    # direction:"both" is the reliable form (the "callers" value returns empty in this engine);
-    # we read the .callers array from it. Payload built with jq so a quote in
-    # --symbol can never corrupt the JSON; an engine failure is unavailable,
-    # never a fabricated empty-impact success.
-    PAYLOAD="$(jq -n --arg p "$PROJECT" --arg f "$SYMBOL" --argjson d "$DEPTH" \
-        '{project:$p, function_name:$f, depth:$d, direction:"both"}')"
-    RES="$(memory_cli trace_path "$PAYLOAD" 2>/dev/null || true)"
-    echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable "$TARGET" "$KIND"
-    echo "$RES" | jq --arg t "$TARGET" '
-        {target:$t, kind:"symbol",
-         impacted: [ (.callers // [])[] | {name:.name, file:(.file_path // ""), qualified:(.qualified_name // ""), hop:(.hop // 1)} ],
-         source:"memory-graph"}'
+    T_ESC="$(gq_escape "$SYMBOL")"
+    DEPENDENTS=gq_q_dependents_symbol; EXISTS=gq_q_exists
 else
-    # File impact: detect_changes maps the working-tree diff to impacted symbols.
-    PAYLOAD="$(jq -n --arg p "$PROJECT" '{project:$p}')"
-    RES="$(memory_cli detect_changes "$PAYLOAD" 2>/dev/null || true)"
-    echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable "$TARGET" "$KIND"
-    echo "$RES" | jq --arg t "$TARGET" '
-        {target:$t, kind:"file",
-         impacted: [ (.impacted_symbols // [])[]
-                     | select((.file // "") | endswith($t) or (. == $t))
-                     | {name:.name, file:(.file // ""), hop:1} ],
-         source:"memory-graph"}'
+    # The graph keys files by repo-relative path.
+    REL="${FILE#"$REPO_ABS"/}"; REL="${REL#./}"
+    T_ESC="$(gq_escape "$REL")"
+    DEPENDENTS=gq_q_dependents_file; EXISTS=gq_q_file_exists
 fi
+
+# Accumulate {q,name,file,test,hop} JSONL in a temp file: the row sets of a hot
+# target can exceed argv limits.
+ROWS="$(mktemp)"
+trap 'rm -f "$ROWS"' EXIT
+TRUNC=false
+for ((k = 1; k <= DEPTH; k++)); do
+    R="$(gq_run "$PROJECT" "$("$DEPENDENTS" "$T_ESC" "$k")")" || unavailable "$TARGET" "$KIND"
+    [[ "$(gq_rows_len "$R")" -lt "$GQ_DEP_LIMIT" ]] || TRUNC=true
+    jq -c --argjson k "$k" '.rows[] | {q:(.[0] // ""), name:(.[1] // ""), file:(.[2] // ""),
+        test:((.[3] | tostring) == "true"), hop:$k}' <<< "$R" >> "$ROWS"
+done
+if [[ -n "$FILE" ]]; then
+    R="$(gq_run "$PROJECT" "$(gq_q_importers "$T_ESC")")" || unavailable "$TARGET" "$KIND"
+    [[ "$(gq_rows_len "$R")" -lt "$GQ_DEP_LIMIT" ]] || TRUNC=true
+    jq -c '.rows[] | {q:"", name:.[0], file:.[0], test:false, hop:1}' <<< "$R" >> "$ROWS"
+fi
+
+# Nothing depends on it: a true negative only if the graph knows the target.
+STATUS=ok
+if [[ ! -s "$ROWS" ]]; then
+    EX="$(gq_run "$PROJECT" "$("$EXISTS" "$T_ESC")")" || unavailable "$TARGET" "$KIND"
+    if [[ "$(gq_rows_len "$EX")" -gt 0 ]]; then STATUS=no-edges; else STATUS=no-match; fi
+fi
+
+jq -s --arg t "$TARGET" --arg kind "$KIND" --arg status "$STATUS" --argjson trunc "$TRUNC" '
+    (group_by([.q, .file]) | map(min_by(.hop))) as $u
+    | ($u | map(.file) | map(select(. != "")) | unique) as $files
+    | ($u | map(select(.test) | .file) | unique) as $tests
+    | {target:$t, kind:$kind,
+       impacted: ($u | sort_by(.hop, .file, .name) | .[:200]
+                  | map({name, file, qualified:.q, hop})),
+       downstream_files: $files,
+       affected_modules: ($files | map(if test("/") then split("/")[0] else "." end) | unique),
+       max_depth: ($u | map(.hop) | max // 0),
+       by_category: {code: ($files - $tests | length), test: ($tests | length)},
+       status: $status,
+       truncated: ($trunc or ($u | length) > 200),
+       source: "memory-graph"}' "$ROWS"

package/scripts/tools/graph-init.sh

@@ -62,7 +62,7 @@ while [[ $# -gt 0 ]]; do
 done
 
 [[ -d "$SCOPE" ]] || { echo "ERROR: --scope '$SCOPE' is not a directory" >&2; exit 1; }
-SCOPE_ABS="$(cd "$SCOPE" && pwd)"
+SCOPE_ABS="$(cd "$SCOPE" && pwd -P)"
 SELF_REPO="$(cd "$TOOLS_DIR/../.." && pwd)"
 
 # --- Resolve ROOT (bounded by the git toplevel; never escapes the repo) ---
@@ -127,22 +127,17 @@ write_root_link() {
     local status="$1"
     local mod_graph="$SCOPE_ABS/draft/graph"
     mkdir -p "$mod_graph"
-    local rel root_project="unknown" root_commit ts schema="$ROOT_ABS/draft/graph/schema.yaml"
+    local rel root_commit ts
     rel="$(root_link_relpath)"
-    if [[ -f "$schema" ]]; then
-        root_project="$(grep -m1 '^project:' "$schema" 2>/dev/null | sed 's/^project:[[:space:]]*//; s/^"//; s/"$//' || true)"
-        [[ -n "$root_project" ]] || root_project="unknown"
-    fi
     root_commit="$(git -C "$ROOT_ABS" rev-parse --verify --quiet HEAD 2>/dev/null || echo none)"
     ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-    # Every interpolated value goes through json_escape: a repo path or engine
-    # project name carrying a quote or backslash would otherwise emit a
-    # root-link.json that no consumer can parse.
+    # Every interpolated value goes through json_escape: a repo path carrying a
+    # quote or backslash would otherwise emit a root-link.json that no consumer
+    # can parse.
     cat > "$mod_graph/root-link.json" <<EOF
 {
   "root_graph": "$(json_escape "$rel")",
   "root_abs": "$(json_escape "$ROOT_ABS/draft/graph")",
-  "root_project": "$(json_escape "${root_project:-unknown}")",
   "root_commit": "$(json_escape "$root_commit")",
   "status": "$(json_escape "$status")",
   "linked_at": "$ts",

package/scripts/tools/graph-preflight.sh

@@ -47,7 +47,7 @@ while [[ $# -gt 0 ]]; do
 done
 REPO="${REPO:-.}"
 [[ -d "$REPO" ]] || { echo "ERROR: '$REPO' is not a directory" >&2; exit 2; }
-REPO_ABS="$(cd "$REPO" && pwd)"
+REPO_ABS="$(cd "$REPO" && pwd -P)"
 
 # --- formatting (color only on a tty, and never in --json) ---
 if [[ -t 1 && "$JSON_MODE" -eq 0 ]]; then B=$'\e[1m'; G=$'\e[32m'; Y=$'\e[33m'; R=$'\e[31m'; D=$'\e[0m'; else B=""; G=""; Y=""; R=""; D=""; fi
@@ -168,6 +168,10 @@ if find_memory_bin "$REPO_ABS" "$SELF_REPO"; then
   ENGINE_FOUND=true
   VER="$("$ENGINE" --version 2>/dev/null | head -1 || echo '?')"
   ok "Engine: $ENGINE ($VER)"
+  PINNED="$(sed -n 's/^DEFAULT_VERSION="v\{0,1\}\([^"]*\)".*/\1/p' "$SELF_REPO/scripts/fetch-memory-engine.sh" 2>/dev/null | head -1)"
+  if [[ -n "$PINNED" && "${VER##* }" != "$PINNED" ]]; then
+    warn "Engine version ${VER##* } differs from the pinned $PINNED the graph tools are verified against — scripts/fetch-memory-engine.sh --force"
+  fi
   # Numeric-only: the value is emitted bare into the --json report, so a
   # non-numeric field (engine output format drift) would produce invalid JSON.
   LIMIT="$("$ENGINE" config list 2>/dev/null | awk '/auto_index_limit/{print $3}' || true)"
@@ -255,8 +259,7 @@ cat <<EOF
 
 Next step (when ready, from the git root):
   scripts/tools/graph-init.sh --scope . --json &     # or: /draft:init --graph-only
-  ${ENGINE:-codebase-memory-mcp} cli list_projects '{}'
-  ${ENGINE:-codebase-memory-mcp} cli index_status '{"project":"<name>"}'
+  scripts/tools/graph-query.sh --repo . --tool index_status
 EOF
 hr
 exit "$VEXIT"

package/scripts/tools/graph-query.sh

@@ -12,11 +12,12 @@
 #                                a `query` field in --json is scanned for write
 #                                verbs exactly like --cypher.
 #
-# 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.
+# Dialect limits (engine v0.9.0 — see _graph_queries.sh for the full list):
+#   SAFE   : comparisons against a literal, `STARTS WITH`, `AND`/`OR`,
+#            variable-length `[:R*1..3]`, rel-type alternation `[:A|B]`,
+#            `coalesce()`, `DISTINCT`, `count(...)`, WITH-aggregation.
+#   UNSAFE : property-to-property comparison, NOT EXISTS(...), NOT (pattern),
+#            path variables, multi-pattern joins. LIMIT applies before DISTINCT.
 # Passthrough returns the engine's raw error, not a silent empty result.
 #
 # Usage:
@@ -52,8 +53,8 @@ Flags:
                  `query` field is write-verb checked like --cypher.
   --help         Show this help.
 
-Dialect: avoid coalesce(), <>, NOT EXISTS, NOT(pattern), WITH-aggregation,
-multi-pattern joins. Use =, <, STARTS WITH, AND/OR, [:A|B] alternation.
+Dialect: avoid property-to-property comparison, NOT EXISTS, NOT(pattern), path
+variables, multi-pattern joins. LIMIT applies before DISTINCT.
 
 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.

package/scripts/tools/graph-snapshot.sh

@@ -11,7 +11,7 @@
 # truth; the engine is the structural index over it.
 #
 # Writes one file under <repo>/draft/graph/:
-#   schema.yaml   engine + project metadata + index counts. Its presence is the
+#   schema.yaml   engine metadata + index counts. Its presence is the
 #                 GATE that tells skills the graph engine is wired for this repo
 #                 (see core/shared/graph-query.md Pre-Check). It carries no graph
 #                 data — every structural query goes to the live engine.
@@ -61,26 +61,18 @@ done
 
 [[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
 
-REPO_ABS="$(cd "$REPO" && pwd)"
+REPO_ABS="$(cd "$REPO" && pwd -P)"
 SELF_REPO="$(cd "$TOOLS_DIR/../.." && pwd)"
 OUT="${OUT_DIR:-$REPO_ABS/draft/graph}"
 
 find_memory_bin "$REPO_ABS" "$SELF_REPO" || { echo "graph engine unavailable — nothing written" >&2; exit 2; }
 command -v jq >/dev/null 2>&1 || { echo "jq required" >&2; exit 2; }
 
-# Index on demand; this is the valuable side-effect — it ensures the engine holds
-# a current index of the repo so live queries resolve.
+# Refresh the engine index (incremental; indexes from scratch when absent). This is
+# the valuable side-effect — live queries resolve against a current index. A failed
+# refresh writes nothing: a fresh `generated_at` over a frozen index would lie.
 PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || { echo "could not index repo — nothing written" >&2; exit 2; }
-
-# ...then ALWAYS re-index. memory_ensure_index calls index_repository only when the
-# project is ABSENT — correct for the graph-*.sh query wrappers, which must stay
-# cheap — so on an already-indexed repo this tool used to write a gate marker with a
-# fresh `generated_at` over a frozen index: a deleted symbol stayed resolvable, a new
-# one never appeared, and nothing in the output said so. Refreshing is this tool's
-# entire job. The engine indexes incrementally, so the repeat call is cheap.
-REFRESHED="$(memory_index_bounded "$REPO_ABS" 2>/dev/null | jq -r '.project // empty' 2>/dev/null || true)"
-[[ -n "$REFRESHED" ]] && PROJECT="$REFRESHED"
+[[ -n "$PROJECT" ]] || { echo "index refresh failed — nothing written" >&2; exit 2; }
 
 mkdir -p "$OUT"
 
@@ -116,32 +108,29 @@ 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.
+# files. detect_changes reports that working-tree delta — echoed so a refresh
+# shows what moved, but kept out of the committed marker (it differs per machine
+# and per run, like the path-derived project name and a timestamp would).
+# Best-effort: never aborts the write.
 CHANGES_JSON="$(memory_cli detect_changes "$(jq -n --arg p "$PROJECT" '{project:$p}')" 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)"
 
-# YAML double-quoted scalars: escape backslashes then quotes so an unusual
-# project name or engine version string can never corrupt the marker.
-PROJECT_Y="${PROJECT//\\/\\\\}"; PROJECT_Y="${PROJECT_Y//\"/\\\"}"
+# YAML double-quoted scalar: escape backslashes then quotes so an unusual
+# engine version string can never corrupt the marker.
 VER_Y="${VER//\\/\\\\}"; VER_Y="${VER_Y//\"/\\\"}"
 
 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
 # the local codebase-memory-mcp engine is wired for this repo. Query the engine
-# live via the graph-*.sh wrappers (or \`codebase-memory-mcp cli <tool>\`).
+# live via the graph-*.sh wrappers (graph-query.sh --tool covers the rest).
 # Counts below are point-of-index provenance; the live engine is authoritative.
 engine: codebase-memory-mcp
 engine_version: "$VER_Y"
-project: "$PROJECT_Y"
-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
 

package/scripts/tools/graph-traces.sh

@@ -4,7 +4,7 @@
 # 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
+# --experimental. NOTE: in engine v0.9.0 ingest_traces is accepted but runtime
 # edge creation is "not yet implemented" — the engine returns its status verbatim.
 #
 # Usage:
@@ -39,7 +39,7 @@ Flags:
   --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
+NOTE: engine v0.9.0 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.

package/scripts/tools/hotspot-rank.sh

@@ -79,7 +79,16 @@ echo "$ARCH_JSON" | jq -e . >/dev/null 2>&1 || unavailable
 # and still reported source:"memory-graph", so a fan-in-only ranking was
 # indistinguishable from a fully measured one. Record the outcome instead, and
 # omit the fields rather than emitting measurements that were never taken.
-if PROPS_JSON="$(gq_run "$PROJECT" "$(gq_q_node_props)")"; then
+# Ask for the hotspots by name: a capped scan of every node missed hotspots past
+# the window on large repos and scored them 0 under enrichment "ok".
+NAMES=""
+while IFS= read -r q; do
+    NAMES+="${NAMES:+,}'$(gq_escape "$q")'"
+done < <(jq -r '(.hotspots // [])[].qualified_name // empty' <<< "$ARCH_JSON")
+if [[ -z "$NAMES" ]]; then
+    PROPS_JSON='{"rows":[]}'
+    ENRICHMENT="ok"
+elif PROPS_JSON="$(gq_run "$PROJECT" "$(gq_q_node_props "$NAMES")")"; then
     ENRICHMENT="ok"
 else
     PROPS_JSON='{"rows":[]}'

package/scripts/tools/mermaid-from-graph.sh

@@ -108,7 +108,7 @@ render_co_change() {
 render_proto_map() {
     local res; res="$(memory_cli get_architecture \
         "$(jq -n --arg p "$PROJECT" '{project:$p, aspects:["routes"]}')" || true)"
-    [[ -n "$res" ]] && echo "$res" | jq -e . >/dev/null 2>&1 || return 2
+    [[ -n "$res" ]] && echo "$res" | jq -e 'has("routes") and (.routes | type == "array")' >/dev/null 2>&1 || return 2
     local edges; edges="$(echo "$res" | jq -r '(.routes // [])[] | "    \"" + ((.method // "")|tostring) + " " + ((.path // "")|tostring) + "\" --> \"" + ((.handler // "?")|tostring) + "\""' 2>/dev/null || true)"
     if [[ -z "$edges" ]]; then return 1; fi
     printf '```mermaid\nflowchart LR\n%s\n```\n' "$edges"

package/scripts/tools/okf-emit-catalog.sh

@@ -82,6 +82,9 @@ sniff_desc() {
 
 write_page() {
     local cid="$1" ctype="$2" resource="$3" fan_in="$4"
+    case "$cid" in
+        ''|/*|*..*) echo "ERROR: concept_id escapes bundle: $cid" >&2; return 1 ;;
+    esac
     local out="$BUNDLE/$cid"
     mkdir -p "$(dirname "$out")"
     if [[ -f "$out" && $FORCE -eq 0 ]]; then