feat: sync portable fixes from upstream colby v1.5.0

.githooks/pre-push

@@ -10,7 +10,8 @@
 #   1. cargo fmt --all --check        (rustfmt)
 #   2. cargo clippy ... -D warnings    (lint, warnings are errors)
 #   3. cargo test --workspace          (incl. golden oracle + sync equivalence)
-#   4. scripts/guardrail.sh            (no AI / vector / LLM crates)
+#   4. scripts/guardrail.sh            (no AI/vector/LLM crates + no release
+#                                       asset-name drift)
 #
 # Enable once per clone:
 #   make hooks            # == git config core.hooksPath .githooks
@@ -45,11 +46,12 @@ if ! cargo test --workspace; then
     exit 1
 fi
 
-echo "==> [4/4] scripts/guardrail.sh (no AI/vector/LLM crates)"
+echo "==> [4/4] scripts/guardrail.sh (no AI/vector/LLM crates + asset-name drift)"
 if ! bash scripts/guardrail.sh; then
     echo "" >&2
-    echo "❌ Scope guardrail failed: a forbidden AI/vector/LLM crate was detected." >&2
-    echo "   This project is deterministic and ML-free by design. Push aborted." >&2
+    echo "❌ Scope guardrail failed: a forbidden AI/vector/LLM crate was detected," >&2
+    echo "   or the release workflow and the installers disagree on asset names." >&2
+    echo "   Read the diagnostics above; push aborted." >&2
     exit 1
 fi
 

.github/workflows/ci.yml

@@ -39,14 +39,40 @@ jobs:
       - name: Clippy lint
         run: cargo clippy --workspace --all-targets -- -D warnings
 
+      # Materializes the frozen v0.40.4 legacy CLI for the Batch M legacy
+      # compatibility tests, using THIS host's NATIVE asset (linux x86_64). The
+      # script verifies the archive digest, the extracted executable digest, and
+      # the real `--version` before exporting the path. A network or digest
+      # failure fails the job here — legacy tests are never skipped.
+      - name: Prepare legacy v0.40.4 fixture (native linux asset)
+        run: echo "CODEGRAPH_LEGACY_BIN=$(bash scripts/setup-legacy-fixture.sh)" >> "$GITHUB_ENV"
+
       - name: Run tests (incl. golden oracle + sync equivalence)
         run: cargo test --workspace
 
       # Windows cross-check is intentionally omitted on Ubuntu: target C deps
       # (tree-sitter/libsqlite3-sys/ring) require MSVC tooling. Runtime
       # correctness is gated by the native windows-latest job below.
 
-      - name: Scope guardrail (no AI / vector / LLM crates)
+      # The guardrail's asset-name drift gate parses release-please.yml with
+      # yaml.safe_load, so PyYAML must be importable. Idempotent: installs only
+      # when the runner image does not already ship it. A missing PyYAML must
+      # never degrade the gate into a silent skip — the gate itself exits nonzero
+      # in that case, and this step fails loudly first.
+      - name: Ensure PyYAML (asset-name drift gate)
+        run: |
+          python3 -c 'import yaml' \
+            || python3 -m pip install --break-system-packages PyYAML \
+            || python3 -m pip install PyYAML
+
+      # The CI-gate integrity block of the guardrail runs the shipped `ci-success`
+      # step body over a synthetic needs context, which needs jq. Present on
+      # ubuntu-latest; asserted here so a missing jq fails loudly rather than
+      # letting the gate degrade.
+      - name: Ensure jq (CI gate-integrity check)
+        run: jq --version
+
+      - name: Scope guardrail (no AI/vector/LLM crates + release asset-name drift + CI gate integrity)
         run: bash scripts/guardrail.sh
 
   windows:
@@ -69,9 +95,27 @@ jobs:
         # codegraph-bench is a Unix-only dev harness (publish=false); excluded from the Windows job.
         run: cargo clippy --workspace --exclude codegraph-bench --all-targets -- -D warnings
 
+      # Same fixture step, but the script selects THIS host's NATIVE asset
+      # (windows x86_64 .zip). There is no cross-execution and no emulation:
+      # the Windows legacy proof runs only here, on a real Windows runner.
+      - name: Prepare legacy v0.40.4 fixture (native windows asset)
+        shell: bash
+        run: echo "CODEGRAPH_LEGACY_BIN=$(bash scripts/setup-legacy-fixture.sh)" >> "$GITHUB_ENV"
+
       - name: Run tests
         run: cargo test --workspace --exclude codegraph-bench
 
+      # Batch M item 16 acceptance: ONE long-lived shipped `serve --mcp` process
+      # releases every SQLite handle when a request completes, so the v2 main
+      # database can be REPLACED (MoveFileEx + REPLACE_EXISTING) without the
+      # compatibility close seam, and the next request serves only the
+      # replacement graph. The replacement rename is the Windows-specific handle
+      # proof (a retained handle makes it fail with a sharing violation), so this
+      # target is selected EXPLICITLY here — never compile-only, never skipped —
+      # even though the workspace run above already covers it.
+      - name: Run Batch M item 16 native Windows replacement acceptance
+        run: cargo test -p codegraph-rs --test batch_m_long_lived_mcp
+
   audit:
     name: Security Audit
     runs-on: ubuntu-latest
@@ -133,18 +177,87 @@ jobs:
           # to repo Secrets to use it; harmless/ignored if unset on a public repo.
           token: ${{ secrets.CODECOV_TOKEN }}
 
+  # ci-success is the SINGLE required status check for branch protection AND the
+  # job the release workflow's `verify-ci` waits on before a release may leave
+  # draft. It must therefore be a STRICT gate: it passes only when every required
+  # job's result is exactly `success`.
+  #
+  # WHY strict (the bug this shape fixes): `needs.<job>.result` can be `success`,
+  # `failure`, `cancelled`, or `skipped`. The previous check rejected only
+  # `failure`, so `cancelled` and `skipped` both PASSED. Combined with
+  # `cancel-in-progress: true` above, a run cancelled by a newer push could still
+  # conclude `CI Success` — and release-please.yml's `verify-ci` gates the release
+  # on exactly that job. A release could then be cut on a run whose tests never
+  # finished. Anything other than `success` now fails, including any result value
+  # GitHub may add in the future (unknown values are not silently tolerated).
+  #
+  # WHY the results are read from `toJSON(needs)` rather than named one by one:
+  # the step body hardcodes no job name, so adding a job to `needs:` below
+  # automatically makes it required with no change to the script. GitHub Actions
+  # cannot make this fully automatic — the `needs` context contains ONLY the jobs
+  # listed in `needs:`, so a new job that is never added there is invisible to
+  # this gate no matter how the expression is written. That gap is closed OUTSIDE
+  # the workflow, loudly: `scripts/check-ci-gate.sh` (run by scripts/guardrail.sh
+  # in `make ci`, the pre-push hook, and the CI `test` job) asserts that
+  # `ci-success.needs` equals every job in this file minus an explicit
+  # informational allow-list, so forgetting to list a new job turns CI red
+  # instead of silently narrowing the gate.
   ci-success:
     name: CI Success
     runs-on: ubuntu-latest
     if: always()
     # NOTE: `coverage` is intentionally NOT listed here — coverage is
-    # informational and must never gate a merge.
+    # informational (codecov.yml sets `informational: true`, baseline ~72% vs an
+    # aspirational 95% target) and must never gate a merge or a release. It is
+    # the ONLY allowed exclusion; scripts/check-ci-gate.sh enforces that, and
+    # also enforces that codecov.yml still marks coverage informational, so the
+    # exclusion can never outlive its justification.
     needs: [test, audit, windows]
     steps:
       - name: Check job status
+        env:
+          # The whole needs context as JSON: {"test":{"result":"success",...},...}
+          NEEDS_JSON: ${{ toJSON(needs) }}
         run: |
-          if [[ "${{ needs.test.result }}" == "failure" || "${{ needs.audit.result }}" == "failure" || "${{ needs.windows.result }}" == "failure" ]]; then
-            echo "❌ CI failed"
+          set -euo pipefail
+
+          if [ -z "${NEEDS_JSON:-}" ]; then
+            echo "::error title=CI gate::the needs context was empty; cannot prove any required job succeeded — failing closed."
+            exit 1
+          fi
+          if ! printf '%s' "$NEEDS_JSON" | jq -e 'type == "object" and length > 0' > /dev/null 2>&1; then
+            echo "::error title=CI gate::the needs context did not parse as a non-empty JSON object — failing closed."
+            printf 'needs context was: %s\n' "$NEEDS_JSON"
+            exit 1
+          fi
+
+          # One row per required job: "<job>\t<result>". A job whose `result` key
+          # is absent renders as <missing> and fails, never passes.
+          mapfile -t rows < <(
+            printf '%s' "$NEEDS_JSON" \
+              | jq -r 'to_entries | sort_by(.key)[] | "\(.key)\t\(.value.result // "<missing>")"'
+          )
+          if [ "${#rows[@]}" -eq 0 ]; then
+            echo "::error title=CI gate::no required jobs were found in the needs context — failing closed."
+            exit 1
+          fi
+
+          echo "Required job results (only 'success' passes):"
+          offenders=0
+          for row in "${rows[@]}"; do
+            job="${row%%$'\t'*}"
+            result="${row#*$'\t'}"
+            if [ "$result" = "success" ]; then
+              printf '  ✅ %-12s %s\n' "$job" "$result"
+            else
+              printf '  ❌ %-12s %s\n' "$job" "$result"
+              echo "::error title=CI gate::required job '${job}' concluded '${result}', not 'success'."
+              offenders=$((offenders + 1))
+            fi
+          done
+
+          if [ "$offenders" -ne 0 ]; then
+            echo "❌ CI failed: ${offenders} of ${#rows[@]} required job(s) did not conclude 'success' (see the ❌ rows above)."
             exit 1
           fi
-          echo "✅ CI passed"
+          echo "✅ CI passed: all ${#rows[@]} required job(s) concluded 'success'."

.github/workflows/release-please.yml

@@ -302,6 +302,30 @@ jobs:
           path: dist
           merge-multiple: true
 
+      # Checksums are computed HERE, from the very same merged `dist/` that the
+      # attach step below uploads, so the sums provably describe the uploaded
+      # bytes. Determinism: `LC_ALL=C sort` on basenames gives a byte-order,
+      # locale-independent ordering; sha256sum is run with cwd=dist so each line
+      # carries the bare asset name (no `dist/` prefix); output is LF-only.
+      - name: Generate SHA256SUMS
+        shell: bash
+        working-directory: dist
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          archives=(*.tar.gz *.zip)
+          if [ "${#archives[@]}" -eq 0 ]; then
+            echo "::error::no release archives found in dist/" >&2
+            exit 1
+          fi
+          mapfile -t sorted < <(printf '%s\n' "${archives[@]}" | LC_ALL=C sort)
+          : > SHA256SUMS
+          for archive in "${sorted[@]}"; do
+            sha256sum "$archive" >> SHA256SUMS
+          done
+          echo "--- SHA256SUMS ---"
+          cat SHA256SUMS
+
       - name: Generate release notes
         uses: orhun/git-cliff-action@v4
         with:
@@ -321,6 +345,7 @@ jobs:
           files: |
             dist/*.tar.gz
             dist/*.zip
+            dist/SHA256SUMS
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

.gitignore

@@ -20,9 +20,7 @@ target/llvm-cov/
 
 # Per-project index DB written by `codegraph init` / `index`.
 .codegraph/
-
-# Local upstream-sync ledger (colby-upstream-sync skill); not part of the repo.
-docs/upstream-sync/
+.codegraph-v2/
 
 # AWS CodeBuild local config (sensitive — never commit)
 .aws/codebuild.env

.oxfmtignore

@@ -9,6 +9,11 @@ changelog/
 .release-please-manifest.json
 release-please-config.json
 
+# Frozen/hash-addressed upstream-sync provenance. These bytes are reviewed and
+# verified by SHA rather than rewritten by the general Markdown formatter.
+docs/upstream-sync/UPSTREAM.md
+docs/upstream-sync/V1_5_COMMIT_MANIFEST.md
+
 # Golden artifacts are byte-compared by the equivalence/golden oracle tests
 # (include_str! / fs::read). Reformatting them breaks the test suite.
 reference/

AGENTS.md

@@ -81,9 +81,10 @@ Full Godot static-analysis scope, static-vs-runtime boundary, and honesty signal
 
 ## HTTP MCP server: background mode + addr-keyed registry
 
-`serve --mcp` (stdio) uses the PER-PROJECT daemon (`.codegraph/daemon.pid` + socket). `serve --http`
+`serve --mcp` (stdio) uses the PER-PROJECT daemon (`.codegraph-v2/daemon.pid` + socket; the whole
+rendezvous is derived from `IndexPaths::current_root`). `serve --http`
 (streamable-HTTP) is different: HTTP servers are keyed by BIND ADDR — a global server (no `--path`)
-spans many projects — so they use a GLOBAL, addr-keyed registry, NOT `.codegraph/`. The registry
+spans many projects — so they use a GLOBAL, addr-keyed registry, NOT the per-project root. The registry
 lives in `codegraph-daemon/src/http_registry.rs`: one `<addr-sanitized>.json` file per running server
 (`HttpServerInfo { pid, addr, mode, project, started_at, version, log_file }`) under
 `$XDG_STATE_HOME/codegraph/http` (else `~/.local/state/codegraph/http`; `%LOCALAPPDATA%\codegraph\http`
@@ -158,9 +159,10 @@ make coverage    # workspace coverage summary (informational; `make coverage-htm
   `Security Audit` (cargo-audit) + `CI Success` gate, on push/PR to `main`.
 - **Release** (`.github/workflows/release-please.yml`): release-please opens a
   release PR; merging it cuts a `v<version>` tag and triggers the pipeline —
-  4-platform binaries (linux musl x86_64/aarch64 via cargo-zigbuild, macOS
-  x86_64/aarch64), git-cliff release notes, and a GitHub Release with the
-  binaries attached. The project is distributed via GitHub Releases +
+  6-platform binaries (linux musl x86_64/aarch64 via cargo-zigbuild, macOS
+  x86_64/aarch64, and Windows MSVC `x86_64-pc-windows-msvc` on `windows-latest`
+  plus `aarch64-pc-windows-msvc` on `windows-11-arm`), git-cliff release notes,
+  and a GitHub Release with the binaries attached. The project is distributed via GitHub Releases +
   `cargo install --git`; it is NOT published to crates.io. Version bumps are
   owned by release-please via `.release-please-manifest.json` — never bump by
   hand.

Makefile

@@ -126,7 +126,8 @@ test:
 	@echo "🧪 Running tests..."
 	$(CARGO) test --workspace
 
-# Scope guardrail: no AI / vector / LLM crates allowed in the workspace
+# Scope guardrail: no AI / vector / LLM crates in the workspace, and no drift
+# between the release workflow's asset names and what the installers download.
 guardrail:
 	@echo "🛡️  Running scope guardrail..."
 	bash scripts/guardrail.sh

README.md

@@ -20,6 +20,7 @@ No AI/LLM anywhere inside the binary — output is byte-stable and deterministic
 ## Table of Contents
 
 - [Quickstart](#quickstart)
+- [Upgrading from v0.40.4](#upgrading-from-v0404)
 - [Installation](#installation)
   - [One-liner install (scripts)](#one-liner-install-scripts)
   - [Prebuilt binaries](#prebuilt-binaries)
@@ -56,13 +57,37 @@ irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/instal
 **Index a project and query it:**
 
 ```bash
-codegraph init  /path/to/project                 # create .codegraph/ and run the first index
+codegraph init  /path/to/project                 # create .codegraph-v2/ and run the first index
 codegraph query "<symbol>" -p /path/to/project   # full-text search
 codegraph serve --mcp --path /path/to/project    # MCP server (--path optional, defaults to cwd)
 ```
 
 ---
 
+## Upgrading from v0.40.4
+
+The per-project index moved out of `<project>/.codegraph/` into an isolated
+`<project>/.codegraph-v2/`. A `v0.40.4` index is **not migrated and not read** —
+this binary never opens, migrates, or writes the old root, so an existing
+`.codegraph/` is simply ignored. Two consequences:
+
+- **Run `codegraph init` again in each project.** Until you do, the project counts
+  as not indexed: `serve --mcp` falls back to direct mode with nothing to serve,
+  and the query commands report `CodeGraph not initialized`.
+- **Old configuration does not carry over.** `.codegraph/config.toml` and
+  `.codegraph/codegraph.json` are ignored. Copy them to
+  `.codegraph-v2/config.toml` and `.codegraph-v2/codegraph.json` if you still
+  want them.
+
+The daemon rendezvous (`daemon.pid`, `daemon.sock`, `daemon.log`) moved with the
+index, so it now also lives under `.codegraph-v2/`.
+
+`codegraph status` reports both roots: `indexPath` is the current one, and
+`legacyIndexPaths` lists any old root still on disk. The old directory is left
+untouched — delete it by hand once you no longer want it.
+
+---
+
 ## Installation
 
 The CLI package is **`codegraph-rs`** — a single binary named `codegraph`. SQLite
@@ -91,7 +116,7 @@ irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/instal
 # Fallback — build from source (only if you have a Rust toolchain)
 cargo install --git https://github.com/sunerpy/codegraph-rust codegraph-rs   # binary: `codegraph`
 
-codegraph init  /path/to/project     # create the index DB (.codegraph/)
+codegraph init  /path/to/project     # create the index DB (.codegraph-v2/)
 codegraph index /path/to/project     # parse + build the graph
 ```
 
@@ -218,7 +243,7 @@ Beyond wiring the MCP server, CodeGraph can install a `SKILL.md` directly into
 each agent's skill directory. The skill teaches your agent to use CodeGraph for
 code research and project onboarding — reach for `codegraph_explore` before
 grep/read, use `codegraph_node` instead of a plain file read on indexed source,
-and run `codegraph init` when no `.codegraph/` index is present yet.
+and run `codegraph init` when no `.codegraph-v2/` index is present yet.
 
 ```bash
 codegraph skill install --yes              # install into all detected agents (global)
@@ -384,8 +409,8 @@ LLM library _inside_ the codegraph binary itself.
 
 CodeGraph spawns a shared background daemon for each indexed project when you run
 `codegraph serve --mcp`. Multiple MCP clients (terminal tabs, agents) share that
-one daemon via a Unix socket (`.codegraph/daemon.sock`). It exits once all clients
-disconnect and the idle timeout elapses.
+one daemon via a Unix socket (`.codegraph-v2/daemon.sock`). It exits once all
+clients disconnect and the idle timeout elapses.
 
 Key operations:
 
@@ -398,8 +423,8 @@ codegraph http stop <addr>     # terminate one HTTP server by address
 
 Set `CODEGRAPH_NO_DAEMON=1` to force foreground mode (useful in CI). The daemon
 watches files with a 2 s debounce; pass `--no-watch` or set `CODEGRAPH_NO_WATCH=1`
-to disable. Custom extension mapping goes in `.codegraph/codegraph.json`; exclude
-patterns in `.codegraph/config.toml` under `[indexing] exclude`.
+to disable. Custom extension mapping goes in `.codegraph-v2/codegraph.json`;
+exclude patterns in `.codegraph-v2/config.toml` under `[indexing] exclude`.
 
 Full env-var table, HTTP server details, filesystem fallback behavior, and the
 Claude prompt-hook: [`docs/mcp.md`](docs/mcp.md) and
@@ -476,6 +501,9 @@ Full list with extensions and per-language notes: [`docs/languages.md`](docs/lan
 - [`docs/godot.md`](docs/godot.md) — Godot static analysis: what CodeGraph
   extracts from `.tscn`/`.tres`/`project.godot`/`.gd`, the static-vs-runtime
   boundary, and honesty signals for dynamic reachability.
+- [`docs/godot-gdext-decision.md`](docs/godot-gdext-decision.md) — why `gdext`
+  (godot-rust GDExtension bindings) is rejected for Godot analysis, and the
+  engine-free alternatives.
 - [`docs/grammar-manifest.md`](docs/grammar-manifest.md) /
   [`docs/embedded-extraction.md`](docs/embedded-extraction.md) — language support
   and extraction tiers (engineering ABI detail).