semanticembed 0.7.4__tar.gz → 0.7.5__tar.gz

{semanticembed-0.7.4 → semanticembed-0.7.5}/.claude/skills/analyze/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: analyze
 description: Scan a repo for infrastructure files (docker-compose, k8s, terraform, GitHub Actions), extract edges, and run 6D structural risk analysis via SemanticEmbed.
-allowed-tools: Bash Read Glob
+allowed-tools: Read Glob
 ---
 
 # /analyze — Structural Risk Analysis

semanticembed-0.7.5/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# Changes to these paths need review from the owner once main has a ruleset
+# that requires code-owner review.
+*                   @jmurray10
+/.github/            @jmurray10
+/src/semanticembed/  @jmurray10

semanticembed-0.7.5/.github/dependabot.yml

@@ -0,0 +1,21 @@
+# Weekly update PRs for the pinned GitHub Actions and the Python dependencies.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python:
+        patterns: ["*"]
+  - package-ecosystem: pip
+    directory: /huggingface
+    schedule:
+      interval: weekly

{semanticembed-0.7.4 → semanticembed-0.7.5}/.github/workflows/ci.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   test:
     name: Test (${{ matrix.python-version }} on ${{ matrix.os }})
@@ -23,10 +26,12 @@ jobs:
             python-version: "3.12"
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          persist-credentials: false
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
@@ -43,9 +48,11 @@ jobs:
     name: Build wheel + sdist
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          persist-credentials: false
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: "3.12"
 

semanticembed-0.7.5/.github/workflows/corpus.yml

@@ -0,0 +1,42 @@
+name: Corpus
+
+# Manual only. Cloning the pinned public repos is not part of every PR.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  score:
+    name: Score pinned corpus
+    runs-on: ubuntu-latest
+    environment: jev  # only jobs in this environment can read TYPESAFE_API_KEY
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev,extract]'
+
+      - name: Score tuning and held-out extraction
+        run: python scripts/corpus_score.py --split all
+
+      # Report only: Jev judges every extracted edge, including edges that
+      # appear only at each repo's current HEAD. Skipped without the secret.
+      - name: Jev edge audit
+        env:
+          TYPESAFE_API_KEY: ${{ secrets.TYPESAFE_API_KEY }}
+        run: |
+          if [ -z "$TYPESAFE_API_KEY" ]; then
+            echo "::notice::TYPESAFE_API_KEY is not set; the Jev edge audit was not run."
+            exit 0
+          fi
+          python scripts/jev/edge_audit.py --log edge_audit_log.jsonl

semanticembed-0.7.5/.github/workflows/jev-drift.yml

@@ -0,0 +1,40 @@
+name: Jev drift
+
+# Weekly check that the Jev model behind the leak guard still answers the
+# fixed cases in scripts/jev/canary_cases.json the way it did when the
+# guard was measured (scripts/jev/canary_baseline.json). Also reports, without
+# failing, how the moving alias jev-latest answers, so a new model release
+# shows up before the pinned version is changed.
+#
+# Needs the secret TYPESAFE_API_KEY in the `jev` environment. About 48 requests a run.
+
+on:
+  schedule:
+    - cron: "17 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  drift:
+    name: Compare with baseline
+    runs-on: ubuntu-latest
+    environment: jev  # only jobs in this environment can read TYPESAFE_API_KEY
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: python -m pip install "httpx==0.28.1"
+
+      - name: Run the drift check
+        env:
+          TYPESAFE_API_KEY: ${{ secrets.TYPESAFE_API_KEY }}
+        run: python -I scripts/jev/drift_canary.py --also jev-latest

semanticembed-0.7.5/.github/workflows/leak-guard.yml

@@ -0,0 +1,88 @@
+name: Leak guard
+
+# Checks the lines a pull request adds for internals of the hosted service:
+# a risk flag's cutoff, the steps that compute a value, how the input graph
+# is changed before scoring, or how ties are broken. Uses TypeSafe's Jev
+# model (scripts/jev/leak_guard.py, measurements in docs/jev.md).
+#
+# Needs the secret TYPESAFE_API_KEY in the `jev` environment. Without it the check fails
+# rather than passing unchecked. Pull requests from forks get no secrets, so
+# they need a maintainer's review for this instead.
+#
+# The guard's code is taken from the base branch, never from the pull
+# request, so a pull request cannot change what runs with the key.
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: leak-guard-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  leak-guard:
+    name: Check added lines
+    runs-on: ubuntu-latest
+    environment: jev  # only jobs in this environment can read TYPESAFE_API_KEY
+    timeout-minutes: 15
+    steps:
+      - name: Check out the pull request (data only)
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+          path: pr
+          persist-credentials: false
+
+      - name: Check out the guard from the base branch
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+          path: trusted
+          persist-credentials: false
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Install the guard's one dependency
+        run: python -m pip install "httpx==0.28.1"
+
+      - name: Run the leak guard
+        env:
+          TYPESAFE_API_KEY: ${{ secrets.TYPESAFE_API_KEY }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          FROM_FORK: ${{ github.event.pull_request.head.repo.full_name != github.repository }}
+          ACTOR: ${{ github.event.pull_request.user.login }}
+        run: |
+          if [ ! -f trusted/scripts/jev/leak_guard.py ]; then
+            echo "::notice::The leak guard is not on the base branch yet. It checks pull requests once it is merged."
+            exit 0
+          fi
+          if [ -z "$TYPESAFE_API_KEY" ] && [ "$FROM_FORK" = "true" ]; then
+            echo "::error::Pull requests from forks get no secrets, so the leak guard cannot run. A maintainer must review the added lines."
+            exit 2
+          fi
+          if [ -z "$TYPESAFE_API_KEY" ] && [ "$ACTOR" = "dependabot[bot]" ]; then
+            echo "::notice::Dependabot pull requests get no repository secrets. Leak guard not run; review the version bumps by hand."
+            exit 0
+          fi
+          cd trusted
+          python -I scripts/jev/leak_guard.py --repo ../pr --base "$BASE_SHA" --head "$HEAD_SHA" \
+            --log ../leak_guard_log.jsonl --json-out ../leak_guard_results.json
+
+      - name: Keep the requests and answers
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: leak-guard-log
+          path: |
+            leak_guard_log.jsonl
+            leak_guard_results.json
+          if-no-files-found: ignore
+          retention-days: 30

semanticembed-0.7.5/.github/workflows/publish.yml

@@ -0,0 +1,112 @@
+name: Publish to PyPI
+
+# Runs on a tag push of the form `v*`: git tag v0.7.5 && git push origin v0.7.5
+# Uses PyPI Trusted Publishing (OIDC), so no PyPI token is stored in GitHub.
+#
+# A release is published only when all of these hold:
+#   1. the tagged commit is on main (a tag on an unreviewed branch is refused);
+#   2. the tag matches pyproject.toml and semanticembed.__version__;
+#   3. the full test suite passes on that commit;
+#   4. someone approves the `pypi` environment. Set required reviewers in
+#      Settings -> Environments -> pypi, and restrict it to `v*` tags.
+#
+# One-time PyPI setup: pypi.org -> Account -> Publishing -> trusted publisher
+#   Project: semanticembed  Owner: jmurray10  Repository: semanticembed-sdk
+#   Workflow: publish.yml   Environment: pypi
+#
+# Actions are pinned to commit SHAs; Dependabot proposes updates.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+jobs:
+  verify:
+    name: Verify tag and run tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Tagged commit is on main
+        run: |
+          git fetch --no-tags origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::Tag $GITHUB_REF_NAME points at a commit that is not on main"
+            exit 1
+          fi
+
+      - name: Tag matches the package version
+        run: |
+          python - <<'EOF'
+          import os, pathlib, re, sys, tomllib
+          tag = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          pkg = tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"]
+          init = re.search(r"__version__\s*=\s*[\"']([^\"']+)",
+                           pathlib.Path("src/semanticembed/__init__.py").read_text()).group(1)
+          if not tag == pkg == init:
+              sys.exit(f"::error::tag {tag}, pyproject.toml {pkg} and __version__ {init} must match")
+          print(f"version {tag}")
+          EOF
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev,extract]'
+
+      - name: Run pytest
+        run: pytest -q
+
+  build:
+    name: Build sdist + wheel
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # trusted publishing; nothing else in this job can write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

{semanticembed-0.7.4 → semanticembed-0.7.5}/CHANGELOG.md

@@ -2,13 +2,77 @@
 
 All notable changes to the SemanticEmbed SDK.
 
+## 0.7.5 — Security fixes, parser corrections
+
+### Security
+
+- **Agent no longer runs the scanned project's hooks.** `semanticembed-agent`
+  started the Claude Code CLI in your working directory with default
+  settings, so a cloned repo's `.claude/settings.json` hooks ran shell
+  commands with no prompt. The agent now loads no settings files, runs the
+  CLI in an empty temporary directory, and has no built-in tools (shell,
+  file read/write, web fetch). Requires `claude-agent-sdk>=0.1.60`; older
+  versions ignore `setting_sources=[]` and are refused at startup.
+- **`extract.from_requirements`** follows `-r` only to files inside the
+  starting file's directory, after resolving symlinks. Lines of a file
+  outside it used to become node names sent to the API.
+- **`find_edges()` LLM fallback** skips `node_modules`, `.venv`, `vendor`
+  and similar directories, skips files that resolve outside the scanned
+  path, and replaces secret-looking values with `[REDACTED]` before
+  sending file text to Anthropic or Google. README "What gets sent where"
+  now covers `find_edges()` and `explain()` / `ask()`.
+- **Skills** no longer pre-approve shell commands.
+- **Releases** publish only from a tag on `main` that matches the package
+  version, after the test suite passes, with approval on the `pypi`
+  environment. Workflow actions are pinned to commit SHAs; Dependabot is on.
+
+### Changed
+
+- **`extract.from_crewai`** reads `@CrewBase` / `@agent` / `@task` / `@crew`
+  crews: agent-to-task edges, the sequential task chain, YAML and inline
+  `context` dependencies, and `manager_agent` fan-out. crewAI-examples
+  `stock_analysis` goes from 0 to 7 edges and `surprise_trip` from 0 to 5.
+- **`extract.from_langgraph`** reads `Command(goto=...)`,
+  `Command[Literal[...]]`, and `Send(...)`, and keeps a separate `START` /
+  `END` per `StateGraph`. A compiled subgraph mounted with `add_node`, or
+  invoked with `ainvoke` / `invoke` / `stream` / `astream`, is wired to the
+  caller. `open_deep_research` `deep_researcher.py` goes from 6 edges (three
+  graphs sharing one `START`) to 16.
+- **`extract.from_terraform`** labels a resource `type.name` when its short
+  name is shared (`aws_vpc.this` vs `aws_internet_gateway.this`). On
+  terraform-aws-vpc this is 55 edges / 35 nodes with a `this` hub, then
+  119 edges / 96 nodes with no bare `this` once module blocks are included.
+  Correct keys put real modules over the free-tier 50-node cap.
+- **`extract.from_directory`** takes `include` and `exclude` source labels.
+  The default still parses every recognized source, including GitHub Actions
+  and Python imports.
+- **Kubernetes names that collide** (`Service` and `Deployment` both called
+  `frontend`) are labeled `Kind/name`. Same-name pairs used to become
+  self-loops and disappear. `GoogleCloudPlatform/microservices-demo`
+  `c7cb6d5` `release/` is 28 edges after that, not 17.
+- **Pulumi / CDK kwargs** such as `vpc_security_group_ids=[group.id]` count
+  as a reference to `group`.
+- **Python `from ._native import`** is resolved against the importing package.
+- **Corpus check** (`corpus/manifest.json`, `scripts/corpus_score.py`):
+  held-out extraction precision 1.0 and recall 1.0 on 2026-11-04
+  (55/55 edges, 6 files). Tuning was 1.0 (59/59). The only pin behind
+  HEAD was this repo, and those labeled files did not change edges.
+  Hosted scoring notes are in `docs/scoring_gaps.md`. The 0.7.4 changelog line "vpc goes
+  from 2 to 56 edges" does not reproduce on vpc `b3abd6df`: the indexed-ref
+  parser before name disambiguation returned 55 edges. With module blocks
+  and brace-matched bodies, vpc `b3abd6df` is 119 edges / 96 nodes
+  (root `*.tf` files alone: 93 edges / 73 nodes). `pyproject.toml` and
+  `requirements.txt` are parsers. A `]` inside a requirement extra does
+  not end a multiline TOML array.
+
 ## 0.7.4 — Terraform count/for_each + Kubernetes auto-detect fixes
 
 - **`extract.from_terraform`** now resolves `count` / `for_each`-indexed
   references (`aws_subnet.this[0].id`, `aws_eip.nat[count.index].id`) — the
   form real modules use almost universally. The ref regex previously matched
-  only `type.name.` and missed them. On terraform-aws-modules/terraform-aws-vpc
-  this goes from 2 to 56 edges.
+  only `type.name.` and missed them. The note below this release said
+  that went from 2 to 56 edges; a remeasure of vpc `b3abd6df` is under
+  Unreleased (119 edges / 96 nodes with the current parser).
 - **`extract.from_directory`** now detects Kubernetes manifests by content
   (`apiVersion` + `kind`) in any directory, not just conventional names like
   `k8s/` / `manifests/`. Manifests under `release/` or `kubernetes-manifests/`

{semanticembed-0.7.4 → semanticembed-0.7.5}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: semanticembed
-Version: 0.7.4
+Version: 0.7.5
 Summary: 6D structural intelligence for directed graphs. Six numbers per node. Sub-millisecond.
 Project-URL: Homepage, https://github.com/jmurray10/semanticembed-sdk
 Project-URL: Documentation, https://github.com/jmurray10/semanticembed-sdk
@@ -22,13 +22,13 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.9
 Requires-Dist: httpx>=0.24
 Provides-Extra: agent-claude
-Requires-Dist: claude-agent-sdk; extra == 'agent-claude'
+Requires-Dist: claude-agent-sdk>=0.1.60; extra == 'agent-claude'
 Requires-Dist: pyyaml>=6.0; extra == 'agent-claude'
 Provides-Extra: agent-gemini
 Requires-Dist: google-genai; extra == 'agent-gemini'
 Requires-Dist: pyyaml>=6.0; extra == 'agent-gemini'
 Provides-Extra: all
-Requires-Dist: claude-agent-sdk; extra == 'all'
+Requires-Dist: claude-agent-sdk>=0.1.60; extra == 'all'
 Requires-Dist: google-genai; extra == 'all'
 Requires-Dist: pyyaml>=6.0; extra == 'all'
 Provides-Extra: dev
@@ -63,7 +63,7 @@ SemanticEmbed computes a 6-dimensional structural encoding for every node in a d
 > - **[Hugging Face Space](https://huggingface.co/spaces/jmurray10/semanticembed-agent-risk)** — zero-install. Paste a LangGraph / CrewAI / AutoGen file, get the encoding + risk findings.
 > - **[Demo dashboard](https://semanticembed-dashboard.vercel.app/)** — interactive 6D explorer with 4 reference apps (sign-in required; click "Try Demo" on the login page for a no-account walkthrough).
 
-> **Validated against production incidents.** In a blind test against a live production Dynatrace environment (108 services, 569 topology-relevant incidents over 30 days), **79.6%** of incidents (453/569) occurred on nodes that 6D structural analysis had flagged as risky — from the call graph alone, before any incident occurred. See [validation methodology](docs/validation_methodology.md).
+> **One private-environment blind test.** On one Dynatrace tenant (108 services, 569 topology-relevant incidents over 30 days), **79.6%** of those incidents (453/569) were on nodes the hosted scorer had flagged. That run is not reproducible from this repo: the matcher and the risk thresholds live in a private service. See [validation methodology](docs/validation_methodology.md). It is one tenant, not a general accuracy number.
 
 ---
 
@@ -72,10 +72,10 @@ SemanticEmbed computes a 6-dimensional structural encoding for every node in a d
 Observability tools tell you **what broke**. SemanticEmbed tells you **what will break** — from topology alone.
 
 - **No agents, no instrumentation** — just an edge list
-- **Sub-millisecond server-side compute** — the encoding kernel itself runs in <1 ms on a 100-node graph; full HTTP round-trip via the cloud API is typically 0.5–2 s including network
+- **Sub-millisecond server-side compute is not something this SDK can show.** `result.encoding_time_ms` is the HTTP round trip, not a kernel timer. The encode response has no separate compute-time field. From this environment on 2026-11-04 a 7-node graph returned in about 0.3–0.4 s, which is faster than the old "typically 0.5–2 s" line. A 100-node kernel time is not measurable on the free tier (the client refuses graphs over 50 nodes before the request).
 - **Works on any directed graph** — AI agent pipelines, microservices, data workflows, CI/CD
 - **Complementary structural axes** — six dimensions, each captures risk signals the others cannot
-- **14 deterministic edge parsers + 3 live connectors** — go from real infra to encoded result in 2 lines
+- **16 deterministic edge parsers + 3 live connectors** — docker-compose, Kubernetes, GitHub Actions, Terraform, CloudFormation, CDK, Pulumi, Python imports, package.json, npm workspaces, pyproject.toml, requirements.txt, OTel JSON, LangGraph, CrewAI, AutoGen; plus Dynatrace, Honeycomb, and Datadog clients
 
 ---
 
@@ -91,39 +91,63 @@ pip install 'semanticembed[agent-claude]'  # adds Claude agent CLI
 
 ---
 
-## Quick Start — from real infra to risk in 2 lines
+## Quick Start
+
+`from_directory` discovers edges. `encode` sends the edge list to the hosted API. Risk text is produced on the server; this package only prints it.
+
+The block below is the report the API returned on **2026-11-04** for this edge list. If the server scorer changes, the words change. It is not a fixture baked into the client.
 
 ```python
 import semanticembed as se
 
-# Auto-discover edges from any directory: docker-compose, k8s, terraform,
-# CloudFormation, AWS CDK, Pulumi, GitHub Actions, package.json,
-# pyproject.toml, OTel traces, Python imports, LangGraph, CrewAI, AutoGen.
-edges, sources = se.extract.from_directory(".")
-print(f"Found {len(edges)} edges from {sources}")
-
-# 6D encode + structural risk analysis (sub-millisecond on the server side).
+edges = [
+    ("frontend", "api-gateway"),
+    ("api-gateway", "order-service"),
+    ("api-gateway", "user-service"),
+    ("order-service", "payment-service"),
+    ("order-service", "inventory-service"),
+    ("payment-service", "database"),
+]
 result = se.encode(edges)
-print(result.table)
 print(se.report(result))
 ```
 
-Output:
+Output (hosted API, 2026-11-04):
 
 ```
 STRUCTURAL RISK REPORT
 ======================
 
-AMPLIFICATION RISKS (high fanout, high criticality):
-  - api-gateway    | fanout=0.667 | criticality=0.556
+SINGLE POINT OF FAILURE:
+  - order-service                  | order-service has high structural criticality (0.122) with limited lateral redundancy (independence=0.00). Failure here impacts 6 transitive path pairs.
+  - api-gateway                    | api-gateway has high structural criticality (0.102) with limited lateral redundancy (independence=0.50). Failure here impacts 5 transitive path pairs.
 
-CONVERGENCE SINKS (low independence, many upstream callers):
-  - database       | independence=0.000
+MONITORING GAP CANDIDATE:
+  - order-service                  | order-service has high criticality (0.122) but sits at depth 0.50, not at the service mesh edge. Likely missing from edge-level observability.
+  - api-gateway                    | api-gateway has high criticality (0.102) but sits at depth 0.25, not at the service mesh edge. Likely missing from edge-level observability.
+  - payment-service                | payment-service has high criticality (0.061) but sits at depth 0.75, not at the service mesh edge. Likely missing from edge-level observability.
 
-STRUCTURAL SPOF (low independence, high upstream dependency):
-  - api-gateway    | independence=0.000 | every request flows through this node
+DEEP BOTTLENECK:
+  - order-service                  | order-service is a bottleneck deep in the pipeline (depth=0.50, criticality=0.122). Failures here are harder to diagnose from edge monitoring.
+  - payment-service                | payment-service is a bottleneck deep in the pipeline (depth=0.75, criticality=0.061). Failures here are harder to diagnose from edge monitoring.
+
+WHAT TO DO
+----------
+  >> api-gateway, order-service: Add a redundant path or fallback service so this node is not the only option at its pipeline stage.
+  >> api-gateway, order-service, payment-service: Ensure this node has dedicated monitoring. It sits on critical paths but is not at the service edge, so it may be missing from your dashboards.
+  >> order-service, payment-service: Add health checks and timeouts. Deep bottlenecks are hard to diagnose from edge monitoring — ensure this node has dedicated alerting.
+
+Total: 7 risks (5 critical, 2 warning, 0 info)
 ```
 
+Directory scan is the same `encode` call after `edges, sources = se.extract.from_directory(".")`. The 16 parsers are docker-compose, Kubernetes, GitHub Actions, Terraform, CloudFormation, AWS CDK (Python), Pulumi (Python), Python imports, `package.json`, npm workspaces, `pyproject.toml`, `requirements.txt`, OpenTelemetry JSON, LangGraph, CrewAI, and AutoGen. The three live connectors are Dynatrace, Honeycomb, and Datadog; this check did not call those APIs.
+
+**Held-out extraction, 2026-11-04.** Hand-labeled files. Micro precision **1.0**, recall **1.0** (55/55 edges, 6 files). Tuning was also 1.0 (59/59 edges, 13 files). Pinned SHAs are in [corpus/manifest.json](corpus/manifest.json). Re-run with `python scripts/corpus_score.py --split held-out`. The only pin that was behind HEAD was this repo (`a612cec` vs `4f1cec9`); the labeled files in it produced the same edges. `package.json` workspaces are covered by a unit test, not by a pinned monorepo.
+
+Two held-out files sit in repos that also contain a tuning file (`crewAI-examples` recruitment crew, `pulumi/examples` S3 website). Those files were not used to edit the parsers.
+
+What to expect from hosted scoring on the voting-app shape, identical twins, and cyclic LangGraph graphs is in [docs/scoring_gaps.md](docs/scoring_gaps.md). The client forwards the edge list unchanged; those outcomes come from the service, not from client bugs.
+
 **Or try it without installing** — [open the Quickstart in Google Colab](https://colab.research.google.com/github/jmurray10/semanticembed-sdk/blob/main/notebooks/01_quickstart.ipynb).
 
 ---
@@ -228,6 +252,10 @@ edges = se.extract.from_github_actions(".github/workflows")
 
 # From Terraform
 edges = se.extract.from_terraform("infra/")
+# Resource names that collide (`aws_vpc.this` and `aws_internet_gateway.this`)
+# are labeled `type.name`. On terraform-aws-modules/terraform-aws-vpc
+# `b3abd6df` that is 119 edges and 96 nodes, over the free-tier cap.
+# The root `*.tf` files alone are 73 nodes. A license is required to encode them.
 
 # From CloudFormation (YAML or JSON)
 edges = se.extract.from_cloudformation("template.yaml")
@@ -415,8 +443,10 @@ The agent has 7 tools: scan, extract (docker-compose, k8s, Python imports), enco
 
 Be explicit about data egress before pointing the agent at private architecture:
 
-- **Claude agent** (`semanticembed-agent` / `python -m semanticembed.agent`): the LLM reads tool outputs as conversation context, so the contents of `docker-compose.yml`, Kubernetes manifests, Terraform `.tf` files, Python source, and `package.json` files in your project go to **Anthropic's API** along with your prompts. Conversation history is governed by Anthropic's data-use policies.
+- **Claude agent** (`semanticembed-agent` / `python -m semanticembed.agent`): the LLM sees your prompts and what the SemanticEmbed tools return: edge lists (node names), which parsers found them, encoding results, and error messages. That goes to **Anthropic's API** and is governed by Anthropic's data-use policies. The agent has no built-in tools (no shell, file read, or web fetch), and it does not load `.claude/settings.json`, hooks, or `CLAUDE.md` from the project it scans. Requires `claude-agent-sdk>=0.1.60`.
 - **Gemini agent** (`semanticembed-gemini-agent` / `python -m semanticembed.agent.gemini_agent`): same data flow, sent to **Google's API** instead.
+- **`find_edges()` LLM fallback**: only when the deterministic scan finds no edges, it sends the text of compose, Kubernetes, Terraform, GitHub Actions, `package.json`, `pyproject.toml`, `Pipfile` and `requirements.txt` files (up to 250 KB) to **Anthropic** (`provider="claude"`) or **Google** (`provider="gemini"`). It skips `node_modules`, `.venv`, `vendor` and similar directories, skips files that resolve outside the scanned path, and replaces secret-looking values (keys, tokens, passwords, URL credentials, Kubernetes `Secret` data) with `[REDACTED]`. Redaction is pattern-based and can miss a secret.
+- **`explain()` / `ask()`**: send the encoding result (node names, the six values per node, risk flags, graph size) and your question to the model you name: **OpenAI**, **Anthropic**, or a local **Ollama** server. No file contents.
 - **Claude Code skill** (`skill/analyze.py`): runs **inside Claude Code** — uses the parent agent for any natural-language extraction, the SDK for the deterministic scan + encoding. No second LLM, no Ollama dependency.
 - **Cloud `encode()` call**: only the **edge list** (node names, e.g. `["frontend", "auth"]`) goes to the SemanticEmbed Railway endpoint. File contents are never sent.