docker(deps): bump python from 3.13-slim to 3.14-slim

Bumps python from 3.13-slim to 3.14-slim.

---
updated-dependencies:
- dependency-name: python
  dependency-version: 3.14-slim
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <support@github.com>

.dockerignore

@@ -18,6 +18,9 @@
 .git/**
 .github
 .github/**
+!.github/requirements/
+!.github/requirements/explorer-extra-py313.txt
+!.github/requirements/pep517-build.txt
 .claude
 .claude/**
 .codex

.github/actions/setup-semantica/action.yml

@@ -0,0 +1,56 @@
+name: 'Setup Semantica'
+description: 'Install Python, cache pip, and install the semantica package into a workflow'
+author: 'Semantica'
+
+inputs:
+  python-version:
+    description: 'Python version to set up'
+    required: false
+    default: '3.11'
+  version:
+    description: 'Version constraint to append to the pip spec, e.g. "==0.6.7" or ">=0.6,<0.7". Leave empty for the latest release.'
+    required: false
+    default: ''
+  extras:
+    description: 'Comma-separated extras to install, e.g. "explorer,all"'
+    required: false
+    default: ''
+  cache:
+    description: 'Pip cache mode passed straight to actions/setup-python ("pip" to enable). Left empty (disabled) by default because this action is meant to run standalone in any caller repo, and actions/setup-python errors out if it cannot find a requirements.txt/pyproject.toml/setup.py/poetry.lock to key the cache on. Opt in only when the caller repo has one of those files.'
+    required: false
+    default: ''
+
+outputs:
+  version:
+    description: 'The installed semantica version'
+    value: ${{ steps.verify.outputs.version }}
+
+runs:
+  using: 'composite'
+  steps:
+    - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+      with:
+        python-version: ${{ inputs.python-version }}
+        cache: ${{ inputs.cache }}
+
+    - name: Install semantica
+      shell: bash
+      env:
+        SEMANTICA_EXTRAS: ${{ inputs.extras }}
+        SEMANTICA_VERSION: ${{ inputs.version }}
+      run: |
+        python -m pip install --upgrade pip
+        if [ -n "$SEMANTICA_EXTRAS" ]; then
+          spec="semantica[$SEMANTICA_EXTRAS]$SEMANTICA_VERSION"
+        else
+          spec="semantica$SEMANTICA_VERSION"
+        fi
+        python -m pip install -- "$spec"
+
+    - name: Verify install
+      id: verify
+      shell: bash
+      run: |
+        VERSION=$(python -c "import semantica; print(semantica.__version__)")
+        echo "Installed semantica $VERSION"
+        echo "version=$VERSION" >> "$GITHUB_OUTPUT"

.github/dependabot.yml

@@ -101,6 +101,29 @@ updates:
     allow:
       - dependency-type: "production"
 
+  # Explorer frontend (npm)
+  - package-ecosystem: "npm"
+    directory: "/explorer"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "03:30"  # 3:30 AM UTC (9:00 AM IST)
+    open-pull-requests-limit: 10
+    reviewers:
+      - "KaifAhmad1"
+    assignees:
+      - "KaifAhmad1"
+    commit-message:
+      prefix: "security"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "javascript"
+      - "security"
+    allow:
+      - dependency-type: "production"
+      - dependency-type: "development"
+
   # Docker dependencies (if you use Docker)
   - package-ecosystem: "docker"
     directory: "/"

.github/requirements/README.md

@@ -0,0 +1,58 @@
+# CI tool requirements
+
+Hash-pinned `pip install` targets for CI/release/Dockerfile steps that install
+something other than the project's own audited `requirements-ci.txt` set.
+These exist because OpenSSF Scorecard's Pinned-Dependencies check flags any
+`pip install` in a workflow or Dockerfile that isn't hash-verified, and
+`requirements-ci.txt` alone doesn't cover build/release/security tooling or
+the project's own local-source install.
+
+Each `.txt` was generated from the adjacent `.in` (or, for `explorer-extra-py311.txt`,
+`explorer-extra-py313.txt`, and `base-deps.txt`, from `pyproject.toml` directly) with:
+
+```
+uv pip compile <input> --python-version 3.11 --python-platform linux \
+  --constraint requirements-ci.txt --generate-hashes -o <output>.txt
+```
+
+(`--constraint requirements-ci.txt` is omitted for `bootstrap.txt`,
+`build-tools.txt`, `uv-tool.txt`, `twine.txt`, `pip-audit.txt`, and
+`security-scan-tools.txt`, since those install standalone tooling with no
+version relationship to the project's own dependency tree.)
+
+Regenerate a file the same way after bumping a pinned version, and re-run it
+whenever `requirements-ci.txt` changes if the file used `--constraint` (see
+each file's own autogenerated header comment for its exact command).
+
+| File | Used by | Installs |
+| --- | --- | --- |
+| `bootstrap.txt` | security.yml, security-scan.yml, benchmark.yml | pip, setuptools (upgrade before anything else) |
+| `pep517-build.txt` | ci.yml, benchmark.yml, Dockerfile | exact `[build-system] requires` from `pyproject.toml` (setuptools, wheel) - installed with `--no-build-isolation` before any `pip install -e .` / `pip install .`, since `--no-deps` alone doesn't stop pip's PEP 517 build isolation from fetching those two *unhashed* |
+| `explorer-extra-py311.txt` | ci.yml | semantica's base deps + the `explorer` extra, resolved for python 3.11 |
+| `explorer-extra-py313.txt` | Dockerfile | the same, resolved for python 3.13 (the image's actual interpreter) |
+| `pytest-tool.txt` | ci.yml | pytest, for the pre-all-extras deterministic test |
+| `uv-tool.txt` | ci.yml | uv, to verify requirements-ci.txt is current |
+| `build-tools.txt` | ci.yml, release.yml | build, wheel |
+| `twine.txt` | release.yml | twine |
+| `pip-audit.txt` | security.yml | pip-audit |
+| `security-scan-tools.txt` | security-scan.yml | safety, bandit, semgrep, jq |
+| `base-deps.txt` | benchmark.yml | semantica's base deps (no extras) |
+| `benchmark-extra.txt` | benchmark.yml | the benchmark-only libs (neo4j, pdfplumber, etc.) |
+
+`explorer-extra-py31{1,3}.txt` and `base-deps.txt` are large (they mirror
+most of `requirements-ci.txt`) because semantica's `dependencies` list in
+`pyproject.toml` isn't extras-gated - installing the package at all pulls
+the full base set. That's expected, not a mistake.
+
+`explorer-extra-py311.txt` and `explorer-extra-py313.txt` are **not**
+interchangeable, and can't be collapsed into one file compiled for either
+version: `librosa`'s `audioread` dependency needs `standard-aifc` /
+`standard-sunau` only under `python_version >= "3.13"` (Python 3.13 dropped
+`aifc`/`sunau` from stdlib). A file resolved for 3.11 simply omits those
+packages' hashes, so installing it with `--require-hashes` on a real 3.13
+interpreter (the Dockerfile's base image) fails outright rather than
+silently under-pinning. Any other file shared across a 3.11 and 3.13
+consumer would need the same split if it hits a similar stdlib-removal
+edge case - check for `ERROR: In --require-hashes mode, all requirements
+must have their versions pinned` on the *other* Python version before
+assuming one `--python-version` covers every consumer.

.github/requirements/benchmark-extra.in

@@ -0,0 +1,13 @@
+rdflib
+neo4j
+faiss-cpu
+torch
+pyarrow
+pdfplumber
+python-pptx
+openpyxl
+lxml
+python-docx
+beautifulsoup4
+chardet
+langdetect

.github/requirements/bootstrap.in

@@ -0,0 +1,2 @@
+pip
+setuptools

.github/requirements/bootstrap.txt

@@ -0,0 +1,10 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile .github/requirements/bootstrap.in --generate-hashes --python-version 3.11 --python-platform linux -o .github/requirements/bootstrap.txt
+pip==26.2.1 \
+    --hash=sha256:71138adf1f4ca900cdb7d289c21b7494329f2332b6d85f0e1c42108c0384ed3e \
+    --hash=sha256:f6ad667e89a1fe78046c8f13232b247200f5258d7828f3f7883d660878e0813f
+    # via -r .github/requirements/bootstrap.in
+setuptools==84.0.0 \
+    --hash=sha256:51a52592b3b99e102b609654876bd65f19f999935166d1352678931132b0c670 \
+    --hash=sha256:f4695c21257f0d9b537ec2692c941d02ee143b7cc1276941349a546573b2ef73
+    # via -r .github/requirements/bootstrap.in

.github/requirements/build-tools.in

@@ -0,0 +1,2 @@
+build==1.6.0
+wheel==0.48.0

.github/requirements/build-tools.txt

@@ -0,0 +1,20 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile .github/requirements/build-tools.in --generate-hashes --python-version 3.11 --python-platform linux -o .github/requirements/build-tools.txt
+build==1.6.0 \
+    --hash=sha256:bd2c8afc603e7a2e0ce70e2ea85f0a6d02043bafbd307f5bada0f98669eca5af \
+    --hash=sha256:f7aaf1ebbb79178a02ba248bb524f2176b256017e17e8e4bd4289c7b38cc2bad
+    # via -r .github/requirements/build-tools.in
+packaging==26.3 \
+    --hash=sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79 \
+    --hash=sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c
+    # via
+    #   build
+    #   wheel
+pyproject-hooks==1.2.0 \
+    --hash=sha256:1e859bd5c40fae9448642dd871adf459e5e2084186e8d2c2a79a824c970da1f8 \
+    --hash=sha256:9e5c6bfa8dcc30091c74b0cf803c81fdd29d94f01992a7707bc97babb1141913
+    # via build
+wheel==0.48.0 \
+    --hash=sha256:3217dcc807155e45db462d7ef2431f5ddda0d7273b700d05a67b271ceb1287ab \
+    --hash=sha256:94800765601e9171bf5d58d066e640662842bcedcbab982b2c90787a2c987322
+    # via -r .github/requirements/build-tools.in

.github/requirements/checkov.in

@@ -0,0 +1 @@
+checkov==3.3.1

.github/requirements/pep517-build.in

@@ -0,0 +1,2 @@
+setuptools==84.0.0
+wheel==0.48.0

.github/requirements/pep517-build.txt

@@ -0,0 +1,14 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile .github/requirements/pep517-build.in --generate-hashes --python-version 3.11 --python-platform linux -o .github/requirements/pep517-build.txt
+packaging==26.3 \
+    --hash=sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79 \
+    --hash=sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c
+    # via wheel
+setuptools==84.0.0 \
+    --hash=sha256:51a52592b3b99e102b609654876bd65f19f999935166d1352678931132b0c670 \
+    --hash=sha256:f4695c21257f0d9b537ec2692c941d02ee143b7cc1276941349a546573b2ef73
+    # via -r .github/requirements/pep517-build.in
+wheel==0.48.0 \
+    --hash=sha256:3217dcc807155e45db462d7ef2431f5ddda0d7273b700d05a67b271ceb1287ab \
+    --hash=sha256:94800765601e9171bf5d58d066e640662842bcedcbab982b2c90787a2c987322
+    # via -r .github/requirements/pep517-build.in

.github/requirements/pip-audit.in

@@ -0,0 +1 @@
+pip-audit==2.10.1

.github/requirements/pip-audit.txt

@@ -0,0 +1,423 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile .github/requirements/pip-audit.in --generate-hashes --python-version 3.11 --python-platform linux -o .github/requirements/pip-audit.txt
+boolean-py==5.0 \
+    --hash=sha256:60cbc4bad079753721d32649545505362c754e121570ada4658b852a3a318d95 \
+    --hash=sha256:ef28a70bd43115208441b53a045d1549e2f0ec6e3d08a9d142cbc41c1938e8d9
+    # via license-expression
+cachecontrol==0.14.4 \
+    --hash=sha256:b7ac014ff72ee199b5f8af1de29d60239954f223e948196fa3d84adaffc71d2b \
+    --hash=sha256:e6220afafa4c22a47dd0badb319f84475d79108100d04e26e8542ef7d3ab05a1
+    # via pip-audit
+certifi==2026.7.22 \
+    --hash=sha256:62f22742b58a1a33014a2b6b706588a8d7e2a88ae7bd1a6ebe8c992928483775 \
+    --hash=sha256:741e2c3b351ddf169a738da9f2c048608ff7f2c5cc02f1ebc6b118bb090d5d55
+    # via requests
+charset-normalizer==3.5.1 \
+    --hash=sha256:00668ebb0609751758682eb0b5857e7c35b9f00e84dfdef062e103244ec94d45 \
+    --hash=sha256:012a22b88a77ca2e59b98ac5889b0deb604147666032f45e6d6e217634d2550d \
+    --hash=sha256:01e93745f7f219b703b60ba7afead36cfc4242782be5af484673fc500df12da5 \
+    --hash=sha256:04368edf83514385ffc3e1cfd4546e595f4f1272dd23ba437a93a9cc3741d47b \
+    --hash=sha256:0722590aabf9dc6a6c0343d523c05458fa2b5047dbe6302fd526bb570600753f \
+    --hash=sha256:07ffd07412fc5d5e84cd8952acf9ff7e4ed7a708e69d1bada19d8ba91711353f \
+    --hash=sha256:09a7bba9f739468c8e78c36a75c33768e53cb1959fc638f510454c14683f00d5 \
+    --hash=sha256:0b2b1b3fa5670c127b246df1d0c059defd41f689a868a3b9d79df9b1cac42d22 \
+    --hash=sha256:0c6dfb5ca6723eeed15aa8e564a014d69fcb8812f94eef11fe3631e0508199f5 \
+    --hash=sha256:0d929fc574b4d6fd9e7c0f5c2ede8716a41911923aa7fa5fce38e0818aa4a1ac \
+    --hash=sha256:13e3afe97712e8887cd516e960c63f0b93122971e5b5e4b2622fe7701771e838 \
+    --hash=sha256:15f024313246a4ed976c60f440bb8d257815513a681d212ff74fd46f7d715a90 \
+    --hash=sha256:195ce897c6153c0700078142cf8efe3e6454ca4cf4357499e4078dfd83396626 \
+    --hash=sha256:19a3dd5aa73cef1c99687c4fc57db016a9c17104ae1185da88ba566a5d3bebe4 \
+    --hash=sha256:1d1c7a53a6c2103925cdd6d7229f8c567379f211c869793df679f2e9f738c369 \
+    --hash=sha256:1f5883d77fd409a261abb5dc8ccbe335720d798b1de4abb3b1d47ccbbc76b53b \
+    --hash=sha256:21b82d8082f6f5e7f456ef0bd16323d08de1266efbfeb476e64b2a91d1471a4e \
+    --hash=sha256:252d099029bcbea642f2a06c4ed5046bdf8b5a8150b64afa5e027e88b106e5ee \
+    --hash=sha256:256dd4d85d9e4dc595e2bc983c980e73f62ddeb3165c58b4c3dfe78c5c8548c1 \
+    --hash=sha256:26422d45fd13551cf564c58932f7d72b4f58b93b0fcf18c35ba6be12b46bb102 \
+    --hash=sha256:2679de311c7946dde5d3b6f44941844133ff5c7cb86099c0061ab1e8901c20a8 \
+    --hash=sha256:29880d17a8eb0b5cfdfd8944b468322928059aa35f1f5fa8ff22b149ec0b42f8 \
+    --hash=sha256:2bced4061f000f7187254a02ad3433ae17eaf991747ceea2f478422590a5bba9 \
+    --hash=sha256:2e9cf9253119d8e5d111f05d71626786fd3d6193817316eab1ca088cdb8593cf \
+    --hash=sha256:2f06b7eae9dbe77fe1d644ca244dad508de8d302870a43f3c559b521270938a0 \
+    --hash=sha256:2f293479cce755c75f1697e87c409b7ae4c555c7dfecb6e988ad13abba943031 \
+    --hash=sha256:329fc3ccb63ad22d867d84c2adea759a64079a37ba4a343433b02c7a2816871e \
+    --hash=sha256:343fb4f2821043bd87095f7b08a1a181febc8e36ac64212143bbfd0a0e1bc235 \
+    --hash=sha256:3588e376b3ea2eea84976f67273d679f229e24c66dce7b82ae45aef04ff6e072 \
+    --hash=sha256:35aea775dc2bd5f54cd84a1cd2696cc3207c479cb9cf0bd346f0d343e4300ddb \
+    --hash=sha256:35fe081843b35aad20ffeccec3eeffbe637b15d14f3fb22cc1b59cd8ec17e93c \
+    --hash=sha256:36047af20e17097c3bb9476c2b7655f2f7aa51322c0ba58c07695bedf755a950 \
+    --hash=sha256:3617ac3cfd8b9888f145ad89dd6e692285834b0201c6074a5eeaad3fd4d668c2 \
+    --hash=sha256:366ec70f5547c640d3ce1985722490f23faf4eb5216a7eeba78277490e78dacb \
+    --hash=sha256:394fea06235c8543390050ed5f529187074b029fb027213f6c46ac11ab5d950e \
+    --hash=sha256:3d27167433c0d5f18dc850f07d0b3816221984fecdc405d6c157a6f0b8f8e9e6 \
+    --hash=sha256:3e5e1224c0a6a90e05843e07adfec669edebec17801c67072f51e59561d63c0b \
+    --hash=sha256:41876ee62a3dddf48ff1121ad8f0798032aa03f2fd35f21f34a4cab14f18d8d2 \
+    --hash=sha256:433c5a81eade63b47e522303bad236f59dba55ea6951746f5558355eeed8c75d \
+    --hash=sha256:4582c27e8c889d64811987b5967fbd3ae0c823fe1fd933b543d55ac20bb475fa \
+    --hash=sha256:485a0d363cafefcd2538a73c7c838daa2035f09b2c9f9b5e3133f80c6aeb84c2 \
+    --hash=sha256:494b70049a4d69aec6e8137c13af4cf8db8c9f9820a1392ac293b0dd2987a818 \
+    --hash=sha256:496846868fea80e479324862fa877f02411f2fd0f83b79ccee2607aa68b2a032 \
+    --hash=sha256:4abdc5f9ad448c1ecbfae2974b820535d6bc6e7eef63babbab3d81cf46968c71 \
+    --hash=sha256:4b599739b93b2cbeded49645ae3c8d1405c29ddfbceac1545c87a3f9580a9e96 \
+    --hash=sha256:4bea7f8ebe90bbd7f0e4a2de42ca6924ba23e3e76418c408ff82f1d46fabd687 \
+    --hash=sha256:4c4fb141a727957c93edfe5c32a26ceb6b5f6461d67146e2d39f51e16170bea8 \
+    --hash=sha256:4c9548dc78002099910abaebc0a72ac58b7d30931869e0351c09b507dff4ece3 \
+    --hash=sha256:4d26f14f041e83dd8edfd61f4cd4fa7285d31798b5bf1f28e70c367ba6c41d61 \
+    --hash=sha256:4f298bdadb8f0b9e5672877f647d1be9373ef5320c9e2f049795e26cad28b6a9 \
+    --hash=sha256:52ec005752a56ae79547a05c0139ca2501a0c866390b6115008456b9f0e7cde1 \
+    --hash=sha256:55261ac0d2941c42f196dd576f543d87a8ee03cd6f5e30dfb4d807b2e3b9121a \
+    --hash=sha256:56490c595a28b1bb27dfc583e816152a9767721ef58b2c03b13f954d2f707420 \
+    --hash=sha256:58d3e12c88e0950bca850ae1f7c256055c097639c2edb9eb123af9807d8b15e4 \
+    --hash=sha256:58d4aa13a59c969dbfdf9e6a9560e242cbfd9e8a8f50c2747714df1a423adf65 \
+    --hash=sha256:59171c6e45bf07d0d5cab3b0bf81d945035530f6873398b3b531c31184d46663 \
+    --hash=sha256:5b6d1386bf0096d26d3a863dc0a487a5b4eb9aa93cf5ba69683d29dde6b9d60f \
+    --hash=sha256:5c0ea61a470e070686aa30892fed79e297d2c8d0ab46b8bcdf027d38c51da591 \
+    --hash=sha256:5c84bec0ab5ae0c64bfe73a7d2adcb5ce73b467523fc27fd6a28ab2aa6cbe35a \
+    --hash=sha256:5ca0555312ae2fe82715cada7fac375530c2f3349e1eaa1bcb33d0283ac79a18 \
+    --hash=sha256:5d8531a6569d025f68e2321e7638fb7978f23db58e5f69f56913837aae03816e \
+    --hash=sha256:5e2d0e146dcb57034f8b97dc58d2d512cb90aba253960ce449f695fec6a82c6f \
+    --hash=sha256:5fc45d653ea8c9a20479167e11d4a0f8cb2fa3470737ab6f9c827532313187b7 \
+    --hash=sha256:6117b84ea48435e5356dc737f5121485c30920ba43375fa7b434fd753df0eac3 \
+    --hash=sha256:6199d5606e2bbf2b096cf64d03f8b6790c91081d5ac866b8e7bb6422738cc60c \
+    --hash=sha256:62b55f6722735a6c472f88361cde6640608773d9443cebdbb51abf436a1fcdd3 \
+    --hash=sha256:687c9ca3035544b113bea2055e180af96fb63c0c476e22a9180f51925186e7b7 \
+    --hash=sha256:6b7430cf5728e68f6c462254009a6ef4086e1bea43cf2f57aa9c55fb4f50ff96 \
+    --hash=sha256:6ba32c4d2abf1d2fe7cf27d280f4cca5664233b0f885549c7761719eb977f486 \
+    --hash=sha256:6c9cdde8becb25a7fde49924511aa2644d6f8081cc8df8e9452724303348d8e3 \
+    --hash=sha256:6df0ec430f9a831772c23ca5a224cba36517a58a84bb32c32bb59a9fa67c47f6 \
+    --hash=sha256:6e2912d4babbc65196ac13c2f53468dc57fb8b9c25ef913e8c59ddf7c6dc0e1b \
+    --hash=sha256:6e5e4d73d588ca5ed09df1b7dcd1b203d1df3c542e3f50d126c947d432b10731 \
+    --hash=sha256:70055ff39b97c99e7ae40ea3e393fb62aa2e44dbd9b29f8d14f42fb0025c3959 \
+    --hash=sha256:706bfd38730a5ac7a365793269a00f4e988178cec121391f4248d84ad8c972e9 \
+    --hash=sha256:7235dc28fc6dd9d832ac7c7bce95367dedb85929f17368a0c2bee1e080b9acbf \
+    --hash=sha256:774d157f112367ff4abd29019f38f023c24e00e56edc7829c20e358a5a913ad8 \
+    --hash=sha256:77efcff2b23071c349402ac1066667a3d011f62398d81408c9b88ad991747c9e \
+    --hash=sha256:789b8982559ae28dad2356519f841655756cdcd96616410590ae0b17454ee64f \
+    --hash=sha256:7ac76cf9afd34929d76eb7fcb63be476a4853d8a96f0dcf2d0db68a0cbdf9885 \
+    --hash=sha256:7c0c10730342b0c9b35dd1d619beb8214e520bd96a1f870f452680b238aab3e0 \
+    --hash=sha256:823f82903d189af463d7df250ef1f7f696f3cee08cc8d91deb565e8d425f6506 \
+    --hash=sha256:838648accb3a7fd9803fd45c87bce8509648eb0c11bc34e216141300977244f2 \
+    --hash=sha256:854066be00447fa8de2ccbbe893e2ffc4b123ef16d897af794c1e18bd4a714b0 \
+    --hash=sha256:85d5855daafc240cc045c026d7a15fd198a09b0fc8ff6f5ecbb5297b509cb11e \
+    --hash=sha256:85de3134b5379856e323ba37c19c9256d39425f7b76a63af52b09fb4664c2e8f \
+    --hash=sha256:87e4f41d375c0b9be2fb5251aee4b8a689169e134535aed81bf085c3b647451e \
+    --hash=sha256:88ca277405c2d3b71c4e1c2ee0e7966e807bcba86a69d11e19ba199d18ae4491 \
+    --hash=sha256:88e85ab89cb822c1e635f51d6d32e488f94e002e70e2f492bdb8b945543f345a \
+    --hash=sha256:8ac8c94b6539074e0f40899301273ac8402b9b3e01c7b7ba269ff30340aaaf20 \
+    --hash=sha256:8fe532b3c966d1fb794e0698e4589d0444017ae77fc0b31edea13c0e35bcc449 \
+    --hash=sha256:9085f87b0e38a2b92b8923059b4e8789fe40d9279712d15dcc670048d77079af \
+    --hash=sha256:90b7481fb62fbe172c558bc6fd1c4c98d82004a54a7551f20e11ac9bf0b8708c \
+    --hash=sha256:92caef967d287a407085d61176fce4012b1dd62daed4eb6d5ceb26d3d2538712 \
+    --hash=sha256:9362dd90aa7dab48c0054a21187791ccf05473f7dba5d92b8033ae62164675e7 \
+    --hash=sha256:94d78ecec2605a8d0398b0f365d5f12a63248438516f5dac536a5eff7337df4a \
+    --hash=sha256:94fbf1c0c6cc0d3d5e50f9a9313a8cdca90dd696d34b381cd1704f8c9e939f20 \
+    --hash=sha256:950f23cb393f85543777b0433f082cddd25b51ab398eac7971146495679efe5f \
+    --hash=sha256:96eefc178f8636b9c760c5829345307fd81cfae9ab1e80997dbddeb0f54ee9a3 \
+    --hash=sha256:96fef3e886d6a9874b14f27fc193fbdc69d5d8035783d86aa4e1cea594e695f9 \
+    --hash=sha256:977cdbd483a9cff38179bea4fd754289a6f2195c7abd414aba85410b3e66cc5e \
+    --hash=sha256:978eab16f55b4ab2c2a745be9a0a840bf8f09a7f227d9c76eb30214d078865a5 \
+    --hash=sha256:994e883d17c559cdfd38c84003c8b27d25424a1077272a17e7cd27bfe0bf57b2 \
+    --hash=sha256:9ac4444d8d4fd4c4bd08bf451ed3167aa9e7ec6cdb41b648794f1d1103652e36 \
+    --hash=sha256:9b5db6052055d34d41230fb78d7c439c23dc536a9896f6cb039e8dd92cfc1263 \
+    --hash=sha256:9d9a0dc7cbe9bec24c3f767c9122c41fe5a1bc43f47cd099d00d393e09769de4 \
+    --hash=sha256:9dbdd9205662134957cf0c324f639bdc5031c0ca056e2369e238db75187c0f11 \
+    --hash=sha256:9eea3ab2597a5e65fe65296e2d6a84570845a6b55532d90333d740d48bbc850a \
+    --hash=sha256:a2028475ba855475b8b4d3cfeb4994269c967aea8b9892dfba907f4263a863a3 \
+    --hash=sha256:a3a370082ce34d0612f421e15fe011c53bb1feff21a26d06ad4fb244dab5a375 \
+    --hash=sha256:a545775cfe815855ea32d7c27731d79da358ef2055b4a25830231b1622dd18aa \
+    --hash=sha256:a5cbd90ecf0fc62e64726917ad083b73001f0563657a87ec3c0b504e277dc90d \
+    --hash=sha256:a6d095662e73e74f0a49988e0593373e243e3a52e27bfeea0a859e88acf4a0f5 \
+    --hash=sha256:a6dac12ff6b846103483683f60c5f8fee205121adc58ffd87e90a90a3af69e99 \
+    --hash=sha256:a951ad59cad9145664a730d3036b40b844e74d2d3683da40111463cd3a83845d \
+    --hash=sha256:aa1099b956fb795e686d073568f6dc002a0bb89765ea6d5b055dd7d9bf1b116c \
+    --hash=sha256:aa2bb0b37202dca27175591f761108b5d34096ade1191ffe4808bdf6b1571488 \
+    --hash=sha256:aae2ee51122d3ae968a3837d97dc24a0aeebb0dea23694422cd172bd30017cd6 \
+    --hash=sha256:ab743e9bc90c1f73552ec33e10e3331315acd2c397b36065b591b0181de533cc \
+    --hash=sha256:ac00177c4831ffa650f8609e4bdddd5fe09c03b1c0c47acece7e6ea20421598b \
+    --hash=sha256:ac13b004224fb341e1e25a1ed5e19d32f57cdb2a403e01f003b46f051a550f6f \
+    --hash=sha256:acaf604462bf330b0d07e7a07c1d6e4adac79e5fb13e9c5140590542cafacc00 \
+    --hash=sha256:ae31a1a1db2ee6cc2942fccaf695c934bc7f3db9f2133a3fef1f367cf1a4ab10 \
+    --hash=sha256:ae4a097991662cd4fff0ddc74e0fe7874f82e00042fa0ea00855645ed0c79598 \
+    --hash=sha256:aea996a6aba25260827c9ea511d1addfde2da9eb686ac961838509086188b7e6 \
+    --hash=sha256:b39b69b347e5e47a3b5b8cfc005c68c1ba347474e3960236c4944a8ecd174962 \
+    --hash=sha256:b54e7e13267d49ffbfe68e25b3cbd774dab38fa37238f71265e91b36146eb21c \
+    --hash=sha256:b9af956078716df40d985fb0dfeb2c2120c5ca92ba4ff4b388acfd01cdc14d08 \
+    --hash=sha256:ba2f37ee79e6338845261a3c5b1784e5d1acdff2c0785b284f1b633033d136ab \
+    --hash=sha256:ba501e667c17d8411f98e67a022d9604ef179aff0e459b7e292c796837c13573 \
+    --hash=sha256:baf3775a2635e5a11fbd5e4e64ee69c7e86875d224a5c72aca4c141064589a90 \
+    --hash=sha256:bb57753e36e4855b8ca375069482250a6246372331a3e4f3407eaebb007443f5 \
+    --hash=sha256:bd6c173f04743d483881bffa1478d5a4624475b8cd1d2194956a75548e191c18 \
+    --hash=sha256:be47f99644b208bff7766314013f9acf57b056b04191d570d68ad14022cf5b1d \
+    --hash=sha256:c010f5581d9c612804cc59fcf7b524b707fbcb72828551237ab545bb5c7034af \
+    --hash=sha256:c1dcc36dcb96abc02236e182d17e0f71430152a6c2c7447421da2d2dc144edea \
+    --hash=sha256:c428c6c31eb5f4277d7f8eccaf767fbd548ddd5ce3c8b4f4cbbfab3d96b5904c \
+    --hash=sha256:c658c50ac0c98cd755a2dd50b7977d3bca7df401dcc47fbdfa87db53ef7d4e8b \
+    --hash=sha256:c71fb0d56c920c269cd3e2e3fe7c610e3f1fdb21a6ce60efa6430ff63676cea6 \
+    --hash=sha256:c7b742bf31c88566b4bb6335a7f393bb322e580b6bb98df7bd0c25e6e3519ce8 \
+    --hash=sha256:cc0329df4caaceb950d2f580b5ac716a377f7059624a0bafaeaf8a218c6ed774 \
+    --hash=sha256:cc5d36d96478aa9c60654bd932525bf32964c62a7281eafdf16d85003a8d6004 \
+    --hash=sha256:ce854f5f478050ade5a238731c4ca985a7d3b3cb53ff600a9b5c3b689b5f0a7a \
+    --hash=sha256:ced3fdd71aaa83ce593746c2edb42b7a59cb4c19c8b5c407781c72e493aae55a \
+    --hash=sha256:cee5dd7c6fb5dd52a0fe2a740f9bc6e3593f5f8b1788bde49de02086f30182b2 \
+    --hash=sha256:cfa1c0cc3a8f9f53f1243a5a99ac36fd003880199383b37672e86ddda9cb07e2 \
+    --hash=sha256:d1ee1e296209fdce05b81b663250eefa02213a2da7b41bf26f7829b8ba3545aa \
+    --hash=sha256:d59b75732e9b6f27388e10c14b0259cc5f2e48c78627d185e6a177b58ad3cffe \
+    --hash=sha256:d63600d620ad0064c3a748b950ac5ea38a80190e5498532efefa4b7b3f1da1f3 \
+    --hash=sha256:dd732602a7009217f658d5863d12d79d373a4de0eebc111094bcdd3bb8e0a6cc \
+    --hash=sha256:e06efa066f7dbadbc84ebc126a97c452a6451dfcf589d89d788484949e1cf795 \
+    --hash=sha256:e199fb99720074809a7720f1c0b4d919eea8b87e88713e0f8f602f7bef543d9d \
+    --hash=sha256:e4b018dc5a0eee4676e38fe84a47a427816c590b93b55d9025274ec4d6ffc2dc \
+    --hash=sha256:e6621fb2a4988d6e53eedc455e5903e2679f3967b8acb3d639f1b63c14a2e893 \
+    --hash=sha256:e71c909f353863b2b89c83de2ebed71ea6d0df8a6ef65a128193c5e650766bef \
+    --hash=sha256:e90251c0c7bdd54a100a0dce3c07b7e637278c93af29dbf78ebb89a58c4bac7d \
+    --hash=sha256:e9fbdce1e47394b09bc9f26ab117dfc8d6491977a11d86f592bb42c779db2fda \
+    --hash=sha256:eb12fb2ba69ffa05f8695f61c69e591dc4b4a12ac3757ac8af8adb259bf56d17 \
+    --hash=sha256:eda059b6bc8bc0812d626fd91a7ce01bf583df0a61296eff390fd94141a34e30 \
+    --hash=sha256:f03ac127268b43ef4fe9e6ab6794a6794b49485a0cc0c1db79876d2f33f75bc7 \
+    --hash=sha256:f298e218441525d3794428b4c8b8fb8662c6d3ea79925d4807ee6b9a96a3bca5 \
+    --hash=sha256:f5542f9b941279d82d41eb0aa9f98eba36fe4df5c7086c651df7944935b37182 \
+    --hash=sha256:f6f7deae3feb4edfa2efaf7c574fe88cbf055038a6abdb40188e4fff66d5699f \
+    --hash=sha256:f9b1e28d0e8dbfa858abdba91d6b547beaf2df1a59bec6da6faae7b96a4991a9 \
+    --hash=sha256:f9f8405c2c758532c74fed975dbee57be1f31a6e865c031870c79a6ed3212ada \
+    --hash=sha256:fa48b1b63d639f9483e0633e092f5851e2348c352f1f9bb6c8182f87884ef876 \
+    --hash=sha256:fb78f6e7fcd8ad785d28cd577168bc1aaee827b25bb8755638f694794ea98f0a \
+    --hash=sha256:fbc597639158fd7c14d55e808718848319540f51b0e6746e3eefa59723a4a348 \
+    --hash=sha256:fce8cbd4997efeb450bd298b54f755dcdff18d496f7a5ddbb4867c6d7c88fdc3 \
+    --hash=sha256:fd0350afdc3aabd5576f60ea109228bd5538139713c7b094c5cd27c73a98bc6f \
+    --hash=sha256:fd0a274c0e5f9a21565cd9d3dd749b61f96b7aa1e20a93aa1ba4029518f2e5c0 \
+    --hash=sha256:fdb8a068947befafba9952162645dc2fecaeb400e64584829ed5e9b2fbe21a7f
+    # via requests
+cyclonedx-python-lib==11.12.0 \
+    --hash=sha256:0e807521a921a5c3cb8ce1153f8a61d29eedfe76a46aac2796b7c6b573391a54 \
+    --hash=sha256:16767c4039de90c04e9f03348f8f0ed4b8ff842eaa7eefcad3a95685f970dacf
+    # via pip-audit
+defusedxml==0.7.1 \
+    --hash=sha256:1bb3032db185915b62d7c6209c5a8792be6a32ab2fedacc84e01b52c51aa3e69 \
+    --hash=sha256:a352e7e428770286cc899e2542b6cdaedb2b4953ff269a210103ec58f6198a61
+    # via py-serializable
+filelock==3.32.4 \
+    --hash=sha256:22e58ca3b1ae3b98993b762d7338367ae64fe50252bf78d59da3bfebcdf1cedd \
+    --hash=sha256:2bde2e4cf732e0153406d8a7bc80620ecf5e621fe0d25e41143c4e3b4733ff30
+    # via cachecontrol
+idna==3.19 \
+    --hash=sha256:5e0811a4383b21dc5838069f801c4fb62113b7447663d2530d2bd6e77b49bf15 \
+    --hash=sha256:815e7be7a7806d54abb586dc943addc79e8b2ee16915059658cbeff4b1b43bf4
+    # via requests
+license-expression==30.4.4 \
+    --hash=sha256:421788fdcadb41f049d2dc934ce666626265aeccefddd25e162a26f23bcbf8a4 \
+    --hash=sha256:73448f0aacd8d0808895bdc4b2c8e01a8d67646e4188f887375398c761f340fd
+    # via cyclonedx-python-lib
+markdown-it-py==4.2.0 \
+    --hash=sha256:04a21681d6fbb623de53f6f364d352309d4094dd4194040a10fd51833e418d49 \
+    --hash=sha256:9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a
+    # via rich
+mdurl==0.1.2 \
+    --hash=sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8 \
+    --hash=sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba
+    # via markdown-it-py
+msgpack==1.2.2 \
+    --hash=sha256:06d95f61de7afe4f4ff908a6feebfcb070d0582ac87c9cf3cedf8551cf634516 \
+    --hash=sha256:0708afbf6a9587f0bfe479a9825c141d14d91e2f6a5c8103cf28bc96f4edb5d9 \
+    --hash=sha256:0883a1578168929fd1640fbbc4614773f1a130e419a8a817dc2918d9af1b651c \
+    --hash=sha256:0a652ceeededf71d3fa40c303a02a149d42338d310162367b91c539d4bd6e0a3 \
+    --hash=sha256:0dd9173c5ebaf5ecc5ca86e7ae1db92934e1d57b856f3dd90698941431f4fd77 \
+    --hash=sha256:0e3315de5a4b2920ccef48d96b4448025e064a10d0f5a250f6584477d839c8d4 \
+    --hash=sha256:0e91332144f69bc3018c91232fac26da580ef748fb8eaddd7914d4458001cc4f \
+    --hash=sha256:0fbc1bed8a535389b41882cfae66376e248cd1680eaa94fd83193c73e1d24986 \
+    --hash=sha256:11e8c421e117d1c36728b423d0402555cccbf0c6f53e288f0e75b6b12100d70f \
+    --hash=sha256:1510f24612d4b983dff6935d9273e02c320cfd525727fbcb58836a75f589fdbc \
+    --hash=sha256:1814f92306ae7862908e9ece7cfd90e0dc87ded3e89b6ae7ffdd1175d6376fdc \
+    --hash=sha256:1e8cdd1f3e7cc52c751092a9bf740e81e6919ab109cd376ae2d965dad0bbae34 \
+    --hash=sha256:1f3af0baafd184436501004828bb3df64eeb2fc49dfe9d89abcf604956094563 \
+    --hash=sha256:1f6b6f8deb07d49090e1808c6ef9cb7d23ca17bef3aa6ed3e5e03df16606e60c \
+    --hash=sha256:226a62ffe99fe54c5c61d910ec64c3449b7766c3280bd286bf6c94838dde239a \
+    --hash=sha256:29cc2d5291711a52956a79a51f41c732329df39ad727c886bd8f0b5b9237a808 \
+    --hash=sha256:336525cc2688e43ea77dfb1a4ce012c8cde561835913801dbfcfdcf4111d8abb \
+    --hash=sha256:34e83e345194a2a51d8bd447dea9de2104f91e75b247f4735f14f04529f0746b \
+    --hash=sha256:352ed831042549cca8be23780e1fe7c9177e65ff02bf183509c4b4d33f671782 \
+    --hash=sha256:3e915d390d7068b257ca8b62f3fc59fad135c8631d1017ab03b0b924b07c5367 \
+    --hash=sha256:419a45c67a5c04213172a14b1864657e014665b77d7081b107a51707923dd39e \
+    --hash=sha256:42fd9260416885b4815caca5bdd14dfd5dda6cdade732d6c09104ef8f6228761 \
+    --hash=sha256:46ec851571d8f1b6e29794ebb9dd36f785008da6d14f57c702e60781d6caf648 \
+    --hash=sha256:4710d881d8fb047deed2485707409116722af2b992d3fefd73c7667c4e350839 \
+    --hash=sha256:4955accbd87f27beebef5f3ecc27503aa74cb016fb4f640868e749fd93194a35 \
+    --hash=sha256:4a4348705be86e029d04e741cf9ed0dfe03e942d7d3b92e838fa80d3aa2c3ebc \
+    --hash=sha256:4b554d8164ebb526892194f71dcd96ef1fefe0c250087498785d3ffc04a80be3 \
+    --hash=sha256:4d9a562aec0a92fe536da2e533d313b3d2a6b929157b1dec7ff623446dc0a8ab \
+    --hash=sha256:51dd39d23cfdea0400ed3ff2d29d1e83bd951d3aea79dc89be5b701a09edfe23 \
+    --hash=sha256:53679573c75cce5f82359e0bd4e6a97809a6b9a9b7a48fd1ba592f4a82cddc84 \
+    --hash=sha256:55faa6f8395e23b848c535ad5dcb96b3462f37f5e7f4ac500d500434f7345da7 \
+    --hash=sha256:58ce37a4a54577115922385d37201d9a44d66d0167dfbbf4770a2e9bf8ea7ba3 \
+    --hash=sha256:59d5b93efa45fd09f620d0c9ba81cde339a2c9937af3eea42ee9653094ce6640 \
+    --hash=sha256:6195257a107bf25872ef84aab7295078271eea3ac6413f0506b631f6c9586ed5 \
+    --hash=sha256:652d1bf13d01bac8fd569def0fe76745e55bcda01e30aa6332d5947ea3788839 \
+    --hash=sha256:682804bf31e43d46e51a9a33bd575b51e839d715ce6bd5612c055f7b28ad637b \
+    --hash=sha256:68df2947921d449f6dcfeafd86cb2cdde13327a8b447534bbe4ee5aaf32a5695 \
+    --hash=sha256:6f53285f20d592ed309ee19e509cc4c77a3bda1db02ad67e8a0949bb227a5a6d \
+    --hash=sha256:73b0e05c32c3cfc3cd84994908e57430c0ebc6813abf905d3f18ff115d54df3f \
+    --hash=sha256:77c2e018417dc1d66f235e383877ee885b60ade9d29e494dd581e08af2cb1923 \
+    --hash=sha256:7826f16edc763e768404f55605ef85dfcf5857e729c1ed29e0d7c180be4fe6d8 \
+    --hash=sha256:7afa5431f6f3487c584187ca6c8e2a34e9b106529893b3e720eabb068f6ac970 \
+    --hash=sha256:7d095df2627e5dd59ac7b0c5ad627a671c76e6020171e03cbe4621a61f0562c3 \
+    --hash=sha256:7fe374ba76eb0ecca13a1703daa8fa85825a6ddddbb52d4c1a732fa524194683 \
+    --hash=sha256:82b1bdf293267afaadcc608b125e7fc6576bb0785a60c4fa7d07c7ab76ed76ec \
+    --hash=sha256:86f173a584f72f6164801f31866d22a581f60c991572cf922aed9ab8eb422b77 \
+    --hash=sha256:8b1415d02e9bf722672af8a90f90813265a0cd0b14163187261e54a5592bc949 \
+    --hash=sha256:8b2a281b556f120a43e591ea39915741b7ad54d4727b9c4350a0a11692252533 \
+    --hash=sha256:8c6321a414f8b4a8dc43976b2fa8349156434ca9adedd9a187b796f7e1d3d3fc \
+    --hash=sha256:8dc4487097571f7311188c3eca2a3e86cd1f1db4c37c7a017bcc3fd38486cbfe \
+    --hash=sha256:90986cc9aab9d7d1d8f38bcbf65d3f7ac83bdd90c35765db7d691b4829698cba \
+    --hash=sha256:9352e6cdb510a7b1a5d3ccaccec730e82e50cf3484a3af7bdaab19e23b9589ff \
+    --hash=sha256:935b1cfad9b908b0fa845010f4271df4c2f04e1cd26e3f18acd61a45f93c9e36 \
+    --hash=sha256:9b659d77f8726fa5e7038967dda6b68d53cf34472c094cfa5b845454713b90d5 \
+    --hash=sha256:9bd3d1557c3fe1a095068210708a03e3e4795973392af6f4047060e70abd9a6c \
+    --hash=sha256:9bf452ff4d4981f25a18e9476e002bcc9263e7928024aa4d7148e25f7be3f929 \
+    --hash=sha256:9d7fb25b4442fae0cb2590272d06ab4f6caa526ee36a994edb81e946b874813e \
+    --hash=sha256:9db1ba1c1e6a84245a9dd866265b56b8a1e9461549cc72ed296d8cbfbd32961b \
+    --hash=sha256:9eb0b0e602064527a045ea28c4f174ed69383587e29cebe28947e3b84106eb2a \
+    --hash=sha256:9fd7f32e2f0fb334e7ecc5adb5cf0458785bd3a9d9d86f950e1715f101cebce5 \
+    --hash=sha256:a378e12ccc06d76efde115caf4073b7e5ff3cc18291d1341f9e65fb882e3f754 \
+    --hash=sha256:a4161eee7799863aee237c35c90427861f7b994416dd81ae829f560b0a81bdcd \
+    --hash=sha256:a9b4cf3685a135666d27d0d7a73fece74e2fad01d9b508fded89e843512f0e90 \
+    --hash=sha256:aa1120c653b76d8eafa50423b5eba06b5c9737f8692c74fa3afe03e84b8978ea \
+    --hash=sha256:b07c03f0da7e5279170df7745ddc732d526c8a198208936ec1a95c11ed2b2d5f \
+    --hash=sha256:b13b59e66f107cca1ba708dd5307179870ca1b15b19fcee7ccf722e5308d9212 \
+    --hash=sha256:b542ffc0a5c531eedc40419f291f1bd659aa8d4223408a5b51c88a2796083fd3 \
+    --hash=sha256:b5c696ae7cd7166b3657261adb855b461ff31f07823fdbae9de8bf80adfccc21 \
+    --hash=sha256:b68614fba0570349833b7dd999ff0aed4e5cc8d9eb6e3a7d4527be33c65e33d3 \
+    --hash=sha256:b8dd6c71d20c28d2d0eb0c51e7cccf3584afde3b1364f6629596186c9025bd54 \
+    --hash=sha256:b9b0c1f2aa7b0026b4bd50718100e8b04175e4f36e160aa852502377b5e572e7 \
+    --hash=sha256:c522420d78db2431887d45b518e304d86e27b9ad0b30f24e3806a6ad5d8bdbfc \
+    --hash=sha256:ccfd880988f8438d1c91c77d7edc58e70f4d2012e999167bc154c64c6f06ea6b \
+    --hash=sha256:cdb6cc6e1127d15879c47a8b3270716243da82d3e7feab1f5946872c75b3d60f \
+    --hash=sha256:cf66fb38703e61a486b01b56d43bb1f50698fbe99b6bd90feba10f24fab60b3b \
+    --hash=sha256:d13d07efbf655f9ae7a2352b630c52727b359005b21ba08a507585c9ac8c0896 \
+    --hash=sha256:d242f3c4ccf55b056e6cf901720dccde58f1df117898f2bbf3bcd6e38ec7c248 \
+    --hash=sha256:d24b38a825bcca41bb956de50eb98451ef291304a8607fad99e619043d3e79b9 \
+    --hash=sha256:d3c247d457ae9079974c7ce3c665396754a6d2baff7eaa51332212a8a5a3f13b \
+    --hash=sha256:d886baa46b2532135e7320067e6a44edb09ba5883a6096b0f9c044533984b8a8 \
+    --hash=sha256:e05a94a0442de86818a30281c6cc2cb9cc7aa148386fd3541c4d4774b73cb3a9 \
+    --hash=sha256:e1b99ad34613d5f8477fa5cf99bc4eaeaf27965588007c102370cd9a78fe9de5 \
+    --hash=sha256:e2eb7ea0ac3911a7aac9d8aaa36d40f216d99455b3274cd3fac38181bcd910cf \
+    --hash=sha256:e497ee34e8a3342bbde51b27c22d8db05a651df3361dd3daef5b3ab0d66f3e04 \
+    --hash=sha256:f11e09f10210a91c169e39c7a5a1f9090eaa73ad75555fafad5023c3053c47ba \
+    --hash=sha256:f466049b8e1ec0854287bbe9a074316826fe0e08dcf707245f98b1ae49e92650 \
+    --hash=sha256:f80361592c13d7226b4379c8941529b63fe1a9d0e05d2de8f3306b70e522b53f \
+    --hash=sha256:ffdd2f4950daf7815490f23087963e3420175b9609520b7ff5df64d351159c22
+    # via cachecontrol
+packageurl-python==0.17.6 \
+    --hash=sha256:1252ce3a102372ca6f86eb968e16f9014c4ba511c5c37d95a7f023e2ca6e5c25 \
+    --hash=sha256:31a85c2717bc41dd818f3c62908685ff9eebcb68588213745b14a6ee9e7df7c9
+    # via cyclonedx-python-lib
+packaging==26.3 \
+    --hash=sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79 \
+    --hash=sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c
+    # via
+    #   pip-audit
+    #   pip-requirements-parser
+pip==26.2.1 \
+    --hash=sha256:71138adf1f4ca900cdb7d289c21b7494329f2332b6d85f0e1c42108c0384ed3e \
+    --hash=sha256:f6ad667e89a1fe78046c8f13232b247200f5258d7828f3f7883d660878e0813f
+    # via pip-api
+pip-api==0.0.34 \
+    --hash=sha256:8b2d7d7c37f2447373aa2cf8b1f60a2f2b27a84e1e9e0294a3f6ef10eb3ba6bb \
+    --hash=sha256:9b75e958f14c5a2614bae415f2adf7eeb54d50a2cfbe7e24fd4826471bac3625
+    # via pip-audit
+pip-audit==2.10.1 \
+    --hash=sha256:1eb4565d19ebe5d48996f4b770b4d2b32887e12cb12cfa637f1a064011b55ffc \
+    --hash=sha256:99ef3f600a317c1945f1e89e227ef26e1c2d618429b8bd3fa6f4f7c440c4611a
+    # via -r .github/requirements/pip-audit.in
+pip-requirements-parser==32.0.1 \
+    --hash=sha256:4659bc2a667783e7a15d190f6fccf8b2486685b6dba4c19c3876314769c57526 \
+    --hash=sha256:b4fa3a7a0be38243123cf9d1f3518da10c51bdb165a2b2985566247f9155a7d3
+    # via pip-audit
+platformdirs==4.11.5 \
+    --hash=sha256:89f8d42695853b89c7170bd49bc3dc593f98a71e695ede88e06a3b247bc4563b \
+    --hash=sha256:e8b31f4f8bcbbedef91a6b57a706255e4f148d2a4e01648382a0a47342539173
+    # via pip-audit
+py-serializable==2.1.0 \
+    --hash=sha256:9d5db56154a867a9b897c0163b33a793c804c80cee984116d02d49e4578fc103 \
+    --hash=sha256:b56d5d686b5a03ba4f4db5e769dc32336e142fc3bd4d68a8c25579ebb0a67304
+    # via cyclonedx-python-lib
+pygments==2.21.0 \
+    --hash=sha256:2363c69b61c4a97c838da3b130dcd6468f4848992b21a82f2a63ec34377137d9 \
+    --hash=sha256:610ca751c9bc2492b38eb9a38a7fbc93edbbb2d7182edaf34e66ae493dee5c8c
+    # via rich
+pyparsing==3.3.2 \
+    --hash=sha256:850ba148bd908d7e2411587e247a1e4f0327839c40e2e5e6d05a007ecc69911d \
+    --hash=sha256:c777f4d763f140633dcb6d8a3eda953bf7a214dc4eff598413c070bcdc117cbc
+    # via pip-requirements-parser
+requests==2.34.2 \
+    --hash=sha256:2a0d60c172f83ac6ab31e4554906c0f3b3588d37b5cb939b1c061f4907e278e0 \
+    --hash=sha256:f288924cae4e29463698d6d60bc6a4da69c89185ad1e0bcc4104f584e960b9ed
+    # via
+    #   cachecontrol
+    #   pip-audit
+rich==15.0.0 \
+    --hash=sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb \
+    --hash=sha256:edd07a4824c6b40189fb7ac9bc4c52536e9780fbbfbddf6f1e2502c31b068c36
+    # via pip-audit
+sortedcontainers==2.4.0 \
+    --hash=sha256:25caa5a06cc30b6b83d11423433f65d1f9d76c4c6a0c90e3379eaa43b9bfdb88 \
+    --hash=sha256:a163dcaede0f1c021485e957a39245190e74249897e2ae4b2aa38595db237ee0
+    # via cyclonedx-python-lib
+tomli==2.4.1 \
+    --hash=sha256:01f520d4f53ef97964a240a035ec2a869fe1a37dde002b57ebc4417a27ccd853 \
+    --hash=sha256:0d85819802132122da43cb86656f8d1f8c6587d54ae7dcaf30e90533028b49fe \
+    --hash=sha256:136443dbd7e1dee43c68ac2694fde36b2849865fa258d39bf822c10e8068eac5 \
+    --hash=sha256:1d8591993e228b0c930c4bb0db464bdad97b3289fb981255d6c9a41aedc84b2d \
+    --hash=sha256:2190f2e9dd7508d2a90ded5ed369255980a1bcdd58e52f7fe24b8162bf9fedbd \
+    --hash=sha256:2c1c351919aca02858f740c6d33adea0c5deea37f9ecca1cc1ef9e884a619d26 \
+    --hash=sha256:36d2bd2ad5fb9eaddba5226aa02c8ec3fa4f192631e347b3ed28186d43be6b54 \
+    --hash=sha256:3d48a93ee1c9b79c04bb38772ee1b64dcf18ff43085896ea460ca8dec96f35f6 \
+    --hash=sha256:47149d5bd38761ac8be13a84864bf0b7b70bc051806bc3669ab1cbc56216b23c \
+    --hash=sha256:4ab97e64ccda8756376892c53a72bd1f964e519c77236368527f758fbc36a53a \
+    --hash=sha256:4b605484e43cdc43f0954ddae319fb75f04cc10dd80d830540060ee7cd0243cd \
+    --hash=sha256:504aa796fe0569bb43171066009ead363de03675276d2d121ac1a4572397870f \
+    --hash=sha256:51529d40e3ca50046d7606fa99ce3956a617f9b36380da3b7f0dd3dd28e68cb5 \
+    --hash=sha256:52c8ef851d9a240f11a88c003eacb03c31fc1c9c4ec64a99a0f922b93874fda9 \
+    --hash=sha256:559db847dc486944896521f68d8190be1c9e719fced785720d2216fe7022b662 \
+    --hash=sha256:5a881ab208c0baf688221f8cecc5401bd291d67e38a1ac884d6736cbcd8247e9 \
+    --hash=sha256:5cb41aa38891e073ee49d55fbc7839cfdb2bc0e600add13874d048c94aadddd1 \
+    --hash=sha256:5e262d41726bc187e69af7825504c933b6794dc3fbd5945e41a79bb14c31f585 \
+    --hash=sha256:5ee18d9ebdb417e384b58fe414e8d6af9f4e7a0ae761519fb50f721de398dd4e \
+    --hash=sha256:7008df2e7655c495dd12d2a4ad038ff878d4ca4b81fccaf82b714e07eae4402c \
+    --hash=sha256:734e20b57ba95624ecf1841e72b53f6e186355e216e5412de414e3c51e5e3c41 \
+    --hash=sha256:7c7e1a961a0b2f2472c1ac5b69affa0ae1132c39adcb67aba98568702b9cc23f \
+    --hash=sha256:7f86fd587c4ed9dd76f318225e7d9b29cfc5a9d43de44e5754db8d1128487085 \
+    --hash=sha256:7f94b27a62cfad8496c8d2513e1a222dd446f095fca8987fceef261225538a15 \
+    --hash=sha256:88dceee75c2c63af144e456745e10101eb67361050196b0b6af5d717254dddf7 \
+    --hash=sha256:8a650c2dbafa08d42e51ba0b62740dae4ecb9338eefa093aa5c78ceb546fcd5c \
+    --hash=sha256:8d65a2fbf9d2f8352685bc1364177ee3923d6baf5e7f43ea4959d7d8bc326a36 \
+    --hash=sha256:96481a5786729fd470164b47cdb3e0e58062a496f455ee41b4403be77cb5a076 \
+    --hash=sha256:a120733b01c45e9a0c34aeef92bf0cf1d56cfe81ed9d47d562f9ed591a9828ac \
+    --hash=sha256:b1d22e6e9387bf4739fbe23bfa80e93f6b0373a7f1b96c6227c32bef95a4d7a8 \
+    --hash=sha256:b8c198f8c1805dc42708689ed6864951fd2494f924149d3e4bce7710f8eb5232 \
+    --hash=sha256:c2541745709bad0264b7d4705ad453b76ccd191e64aa6f0fc66b69a293a45ece \
+    --hash=sha256:c742f741d58a28940ce01d58f0ab2ea3ced8b12402f162f4d534dfe18ba1cd6a \
+    --hash=sha256:c7f2c7f2b9ca6bdeef8f0fa897f8e05085923eb091721675170254cbc5b02897 \
+    --hash=sha256:d312ef37c91508b0ab2cee7da26ec0b3ed2f03ce12bd87a588d771ae15dcf82d \
+    --hash=sha256:d4d8fe59808a54658fcc0160ecfb1b30f9089906c50b23bcb4c69eddc19ec2b4 \
+    --hash=sha256:da25dc3563bff5965356133435b757a795a17b17d01dbc0f42fb32447ddfd917 \
+    --hash=sha256:eab21f45c7f66c13f2a9e0e1535309cee140182a9cdae1e041d02e47291e8396 \
+    --hash=sha256:eb0dc4e38e6a1fd579e5d50369aa2e10acfc9cace504579b2faabb478e76941a \
+    --hash=sha256:ec9bfaf3ad2df51ace80688143a6a4ebc09a248f6ff781a9945e51937008fcbc \
+    --hash=sha256:ede3e6487c5ef5d28634ba3f31f989030ad6af71edfb0055cbbd14189ff240ba \
+    --hash=sha256:f3c6818a1a86dd6dca7ddcaaf76947d5ba31aecc28cb1b67009a5877c9a64f3f \
+    --hash=sha256:f758f1b9299d059cc3f6546ae2af89670cb1c4d48ea29c3cacc4fe7de3058257 \
+    --hash=sha256:f8f0fc26ec2cc2b965b7a3b87cd19c5c6b8c5e5f436b984e85f486d652285c30 \
+    --hash=sha256:fd0409a3653af6c147209d267a0e4243f0ae46b011aa978b1080359fddc9b6cf \
+    --hash=sha256:ff18e6a727ee0ab0388507b89d1bc6a22b138d1e2fa56d1ad494586d61d2eae9 \
+    --hash=sha256:ff2983983d34813c1aeb0fa89091e76c3a22889ee83ab27c5eeb45100560c049
+    # via pip-audit
+tomli-w==1.2.0 \
+    --hash=sha256:188306098d013b691fcadc011abd66727d3c414c571bb01b1a174ba8c983cf90 \
+    --hash=sha256:2dd14fac5a47c27be9cd4c976af5a12d87fb1f0b4512f81d69cce3b35ae25021
+    # via pip-audit
+typing-extensions==4.16.0 \
+    --hash=sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8 \
+    --hash=sha256:dc983d19a509c94dba722ee6abd33940f7c05a89e243c47e907eb4db6f1a43e5
+    # via cyclonedx-python-lib
+urllib3==2.7.0 \
+    --hash=sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c \
+    --hash=sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897
+    # via requests

.github/requirements/pytest-tool.in

@@ -0,0 +1 @@
+pytest==9.1.1

.github/requirements/pytest-tool.txt

@@ -0,0 +1,32 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile .github/requirements/pytest-tool.in --generate-hashes --python-version 3.11 --python-platform linux --constraint requirements-ci.txt -o .github/requirements/pytest-tool.txt
+iniconfig==2.3.0 \
+    --hash=sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730 \
+    --hash=sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12
+    # via
+    #   -c requirements-ci.txt
+    #   pytest
+packaging==26.3 \
+    --hash=sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79 \
+    --hash=sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c
+    # via
+    #   -c requirements-ci.txt
+    #   pytest
+pluggy==1.6.0 \
+    --hash=sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3 \
+    --hash=sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746
+    # via
+    #   -c requirements-ci.txt
+    #   pytest
+pygments==2.20.0 \
+    --hash=sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f \
+    --hash=sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176
+    # via
+    #   -c requirements-ci.txt
+    #   pytest
+pytest==9.1.1 \
+    --hash=sha256:1088fbde8f2b49d95a549a195707afa7a76a3ce9bcadc26b6d71f0ffda5fe313 \
+    --hash=sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c
+    # via
+    #   -c requirements-ci.txt
+    #   -r .github/requirements/pytest-tool.in

.github/requirements/security-scan-tools.in

@@ -0,0 +1,4 @@
+safety==3.8.1
+bandit==1.9.4
+semgrep==1.175.0
+jq==1.12.0

.github/requirements/twine.in

@@ -0,0 +1 @@
+twine==7.0.0

.github/requirements/twine.txt

@@ -0,0 +1,470 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile .github/requirements/twine.in --generate-hashes --python-version 3.11 --python-platform linux -o .github/requirements/twine.txt
+backports-tarfile==1.2.0 \
+    --hash=sha256:77e284d754527b01fb1e6fa8a1afe577858ebe4e9dad8919e34c862cb399bc34 \
+    --hash=sha256:d75e02c268746e1b8144c278978b6e98e85de6ad16f8e4b0844a154557eca991
+    # via jaraco-context
+certifi==2026.7.22 \
+    --hash=sha256:62f22742b58a1a33014a2b6b706588a8d7e2a88ae7bd1a6ebe8c992928483775 \
+    --hash=sha256:741e2c3b351ddf169a738da9f2c048608ff7f2c5cc02f1ebc6b118bb090d5d55
+    # via requests
+cffi==2.1.1 \
+    --hash=sha256:046bfc24911b37851ee1b51aab8bffe713d89c68c6a057b09484ce9fd5f69b4e \
+    --hash=sha256:06c72bb76605a4b0cd0aad6930b69d4baf7dd5d806cfc409b824191099700e66 \
+    --hash=sha256:0beceaabe56af686895136a2de78db54ecd8e4046b236b8fd6d6cb61389e9bf2 \
+    --hash=sha256:154852545011f779917b11c78db2358d095da62a9a172b78ad0a583ee5adc0d0 \
+    --hash=sha256:194cffa889098ced9976c3fc6340305e43f6303657d298da55366907c05c22d6 \
+    --hash=sha256:19ee6127ee34de7d83ce3d371ebc5ed91addbdcc39f9ab15ce4eb35a4e534971 \
+    --hash=sha256:1a18a57b58cfb21fc28d72e876acf10eaed67a1ed96226f92af4df681d571c4c \
+    --hash=sha256:1aa5645c30469b09530c4ebca77ebf8f17618293c58f8549cb1a543a50236e7d \
+    --hash=sha256:1dea0e4d7d4f11f619fe8c1d76caf49e24405b4b5743c0e3be16a500ecd930c9 \
+    --hash=sha256:208f941bb9d18e768138677f0a6d2ce01f590df56043dda1df1535ac57c88517 \
+    --hash=sha256:210019b6c7cf07f081b4c54635c8cf744377001350e29cc0f81c4377b4797735 \
+    --hash=sha256:246fa40ce8645a614ff682e0b70f37134e460eaf93a775e0cbe3cca585a67a80 \
+    --hash=sha256:25792eac27877609e7bb06d42ff88278a6624fff2ba9bbb523c09616b117e80f \
+    --hash=sha256:27350daa11d4f10c540e6e89dada4c54feb7256ad03e9a4dc075ebad7ba360d1 \
+    --hash=sha256:28907ab9bfb6aa13184cfc17c6b8e1023c5ab6fd7076d8c20a35e59fe04f8f29 \
+    --hash=sha256:2ae64be792b8966f2c69538199728b290e34726562896df1e5dc8ffd8d8188e8 \
+    --hash=sha256:31348097ff5bbe827ccc41795d4dd099d9f0625e7def00ee653c137a490c2a6c \
+    --hash=sha256:3143d81e29e1e20a9ce10901ec369012947876596f75a222235965f2b7ae832e \
+    --hash=sha256:3222ba5d678f80a030e6afbcc33dc1ae5cb45facabb61cee2c7016b8432fde48 \
+    --hash=sha256:3311ed60d36f83378794e1009ac6258bafbf81f7888b4caa7b35a521e3f95813 \
+    --hash=sha256:334644fbac4eff73d985a17a91226df55d0f394160c4cfb880e084c8f7161cac \
+    --hash=sha256:34e261f78cb6ceaaa36f42f2613f4380d94d9c759a9c73c769ee6e0247364632 \
+    --hash=sha256:363e05fa78e15116c3c32c210ee36884fd6b9afa6d440e47112c3bd511d64cb6 \
+    --hash=sha256:398aff33cee2767e3e781d2554c54bd0dff386bb437581e0d8011fde1a942ec1 \
+    --hash=sha256:3d22a20b1fb1632cc72c22f95f7b0d2961c3e1c235f245ba4c606c4771035659 \
+    --hash=sha256:42a494cee34437f05546455144f2b5d9ac09b1face62bcfce597d2e521066688 \
+    --hash=sha256:42e2f76b9455f5a9a844f770bf3e200ed3da0e15f5df3db9c31fe80b04b3d004 \
+    --hash=sha256:42f6930c31dc7f50732c9ae793c2786c7b6b044195967bbdde40bb9be81c4cc0 \
+    --hash=sha256:456a61fa52d579ebf9df2e9552ead5129855dbaff6c1e5a9b1bc408809bdc062 \
+    --hash=sha256:471cee653ae88de62096552e6d24ccb4a5adb8c8c9f10b5054d0122c15bf2779 \
+    --hash=sha256:49cbc70e6542d4ccccb936558d1064a8012541e78f821f955cff24e357776c94 \
+    --hash=sha256:4a7c934f7360e8cd64fe9efadcbd10c7c6364f531e432b9a4bf5ccbc9e0e8b50 \
+    --hash=sha256:4be96343e422f2dfcd12ab5c9f5aebe03f82f737c6bffeca6830b3875cb44aab \
+    --hash=sha256:4f42141fc14250de6dde5ee7ea4432be017252d91f19c5ad043c084cea629cac \
+    --hash=sha256:507a24c282e0f42f8ed737cf048572cbf580468da5555764a8331735e9c736b6 \
+    --hash=sha256:51b31d1c98274844cfd7838ce00bfc27c7423a4dc00fc0772fc3331c2cc90676 \
+    --hash=sha256:58acb8ab8e295e6c5ea12f888cbb13cf21511ef2a3303a23f4325c29d17fe5c1 \
+    --hash=sha256:5a59cc1c4442bc3d5c703bf720b51138d0bfc173618807c9ee2490a7541dd3d9 \
+    --hash=sha256:5bb4e7ea95dcd6a014a6fef62e62467d67d8e582326443f3d68e71d6320a9fcf \
+    --hash=sha256:5c58fe613dc5e5336357eff555824a314d8e43282600435c8d1cb6a7a2fedd13 \
+    --hash=sha256:5e7cecbaadb83884793e05828cee59b210b24583b9c7425d0ba6a754fe22eb4e \
+    --hash=sha256:616f097f2fe415bc92a247f02e11f634e1f9e9a83d327e3c915c15089c87869e \
+    --hash=sha256:63bbfd5ded17c4840ac07cd8f1c21ba9d9708141f840b324f422f41b207e3973 \
+    --hash=sha256:64faea20f4e2613363a1a9b9c7dd73058f3ecd00133a511e72ad7c511658f527 \
+    --hash=sha256:661c298b4821edebead0c91edd2b00374d67ad7c5a1f7a91d4442633b79d6a72 \
+    --hash=sha256:68e62fe11f30d5ca8289242866f0a5291402d8529ca2178ab8afc5c9694ae890 \
+    --hash=sha256:6a8dddef476fab96d066d578fc88526767b836ab5ab21754e1d5bf3879c31c7c \
+    --hash=sha256:6e192623c49c94421616a5778fba35cf0d5a8d000650c1967ef4448ee5cdd990 \
+    --hash=sha256:7225e4514edb64eb6740324353e0da0711954fd8d7da4576755b1c6e09b697cd \
+    --hash=sha256:75f80557d1389eddbd0de2681f6a390a0c5338c31ddaa821381c203fc3fd50d9 \
+    --hash=sha256:770de9db11e84213beec501cfcaa013b019820ca881e03344dea5844f7876d94 \
+    --hash=sha256:7750c6449dff7864bb9bb27ddfb0267756189201a3afc911d82b3caacd70dfc3 \
+    --hash=sha256:7bde5e4cc5c10140859842b9d383af292b22639a4dffb725314baf45968cef80 \
+    --hash=sha256:7ce713ace7c0e4520535b42b77eaa742c16dab813978064913e5a3cf82973b41 \
+    --hash=sha256:7da0c5eff80f0197f3b3d1232ec5a682a9325f4ae9016a78f5f5ca35f9ced1f5 \
+    --hash=sha256:7dbb61fe3a7699468030f71bbe5f8a0e326a151daa91beb11a6fc1f980c55e1c \
+    --hash=sha256:811bd1e21d32de12efca32393a0ab3f5133b54fce9bd44b8bd77ab07da14bf6a \
+    --hash=sha256:8ef53b2de9bcb9197d31854256575d59dbac0cba72ac627bb291ef5eceb74be4 \
+    --hash=sha256:937c0052c05a31ca1daf18de3158eed4dbfcb9cc107adbea227728d647be701e \
+    --hash=sha256:9d2055050ea716bd38b7f7f1579c275386646b4894c155a3e2f3cd62ed41b7c6 \
+    --hash=sha256:9f8d177621de5cb38ee3e731eda45d421db093ec0739f46a5594babda7987a98 \
+    --hash=sha256:a2d7755bef5a12ed488f4ef1f1b69ee9191d7396083b755a5d2295f6edb4768b \
+    --hash=sha256:a48d62ab9d6f4f98c983223a547af44be6ca3691074c31cecced6facd3ba2dc1 \
+    --hash=sha256:a4f00aa42f75d6e4595e8866e748cc1705adc0cddfeb2ca86d0d03993d63ba03 \
+    --hash=sha256:a6e721d4b0e45d5b65e87534470e67b18dcd092c83f68fba09f152b9cbc061af \
+    --hash=sha256:a730a083190634c65cca36ba5f489531576ebd79bcd5c8e172130f6453127231 \
+    --hash=sha256:a931079504ecc49efed7744c476a5c343a92fabf66dec2db95edb1b2fdc770e2 \
+    --hash=sha256:aa9511c62d14da7aacc9b4bf51f3f697a621e83b2d6919008243c3aad168eea3 \
+    --hash=sha256:ab36d55f9ed2d067327667c2fea18dda018eb628dd6347aa01dda6cf1f5d3836 \
+    --hash=sha256:ad2c86c495b899d862ea0f4b42891b8713a3bd45dd4105c7fd51c2a72f39f3a5 \
+    --hash=sha256:aeae0e330c9f6acd681f647d46cefd30c29f93e3392882e792e82080c9691399 \
+    --hash=sha256:b0431303acaea1089ad4b3e9ce4e6518193def1118d4073ca848635ee4ea2e96 \
+    --hash=sha256:b5bdfd1c873d4e093aabc0ca84c4ca6dbc4f752afb5c86f146d9742580c9da2e \
+    --hash=sha256:baed1e86cc735622097354b9d1281406caf42ff42a886d29faa8e8d1630333be \
+    --hash=sha256:c1453022f490d2459a11819d83ad1d586e9ff65a12ac3e705ffebd46d3685dcf \
+    --hash=sha256:c26608d2222fb1e94487e4a387d85f13eb55d5ed725cb25a0c589ac4ee60e7bc \
+    --hash=sha256:c7659f22557c5a0bc4855cd635f55edec690cc008a40768527762cb9fb263455 \
+    --hash=sha256:c8c69575568085ba0b1b10c0249d779a214aea6f6522e949a0fc9fb0fcb449d0 \
+    --hash=sha256:c8d2c9fd1f2d16f780d15127abb050d13d1a76c03a4bd87d7e4980e45e511e12 \
+    --hash=sha256:ca82be1a1d406ecfe1d25dc16cb33488e5a16bf4438c9fb590484ea29d92478b \
+    --hash=sha256:cc572dace3f60ef98d7b12ff411d20f5362feb31a0439eab0085bbfd349982d7 \
+    --hash=sha256:d18e5ac0f2f03f4f518d3e23db0f0cad7faa1da8620e9c09461d443bbf6e6692 \
+    --hash=sha256:d28630f5854ab07ab1fd4aba756de52326c82e6be15d414b12793f1975048b54 \
+    --hash=sha256:d9c275eaacd24aa73f94ffd6de08fc3f932424d8b6c376f4bed7cde376fe7bc3 \
+    --hash=sha256:da0e573f9f97159390c89d9f1a9e41908b66d408cc5b58d08cf3847d844c531b \
+    --hash=sha256:dd31f52ea1086513bb9df30f8fcee9b8918323ae067a3d5b78bc826a000712be \
+    --hash=sha256:dddad92b554513a31f272570678ba307fb9f618f05e3d4a5eacafff9eae03e1d \
+    --hash=sha256:df423d40ee8654634421812bc3b196da3f9bd7d32929da813f8394c4348a5358 \
+    --hash=sha256:df913725b79db7bcf03448f36b7bf8815363417d5b58deecf9305e3e30f0f21a \
+    --hash=sha256:e0bcb7e0f677f543555d2adff3bf19c05f66cdb4796e5ff602442ab2fe3c4ef7 \
+    --hash=sha256:e2d65b31f36619cda3999b78b2aa9632e76b78448e7a56fc4240824200e7c4fc \
+    --hash=sha256:e6e8cff14d6fb0be70a09c0bdc58096f501952d04624ebf867e0e56da2df8960 \
+    --hash=sha256:f16c709686a78c727bbbf059f92b0bf41c6fc60deec706d2dc19f529175a6125 \
+    --hash=sha256:f24fb43132a4c6b4cb4eb029492919b2db645be6808d738f244fd146c03c32cb \
+    --hash=sha256:f53e442b08449d42821fa4a4fba000095af9f62742a500f978a9f557ec44339a \
+    --hash=sha256:f5cfbc5fe74540d335175b656c725d74d90e3730c626d92575eea35029d9afaa \
+    --hash=sha256:f81b3b8f3d4e343550fa4baa0e479bba9f2d29ce9c2e9b51d1ce1718d7442fcf \
+    --hash=sha256:f8ec5e643a9a937f64e1999eb9f75d072263751912dc5cd06d3c85f8f44be7c3 \
+    --hash=sha256:fb92203a88b3d3053034db775110081c49d28be6551923805e039924093761e4 \
+    --hash=sha256:fcd22650c908d7b7da162bbfaab594a1227a15d1643a98c68b122ac642fa2264
+    # via cryptography
+charset-normalizer==3.5.1 \
+    --hash=sha256:00668ebb0609751758682eb0b5857e7c35b9f00e84dfdef062e103244ec94d45 \
+    --hash=sha256:012a22b88a77ca2e59b98ac5889b0deb604147666032f45e6d6e217634d2550d \
+    --hash=sha256:01e93745f7f219b703b60ba7afead36cfc4242782be5af484673fc500df12da5 \
+    --hash=sha256:04368edf83514385ffc3e1cfd4546e595f4f1272dd23ba437a93a9cc3741d47b \
+    --hash=sha256:0722590aabf9dc6a6c0343d523c05458fa2b5047dbe6302fd526bb570600753f \
+    --hash=sha256:07ffd07412fc5d5e84cd8952acf9ff7e4ed7a708e69d1bada19d8ba91711353f \
+    --hash=sha256:09a7bba9f739468c8e78c36a75c33768e53cb1959fc638f510454c14683f00d5 \
+    --hash=sha256:0b2b1b3fa5670c127b246df1d0c059defd41f689a868a3b9d79df9b1cac42d22 \
+    --hash=sha256:0c6dfb5ca6723eeed15aa8e564a014d69fcb8812f94eef11fe3631e0508199f5 \
+    --hash=sha256:0d929fc574b4d6fd9e7c0f5c2ede8716a41911923aa7fa5fce38e0818aa4a1ac \
+    --hash=sha256:13e3afe97712e8887cd516e960c63f0b93122971e5b5e4b2622fe7701771e838 \
+    --hash=sha256:15f024313246a4ed976c60f440bb8d257815513a681d212ff74fd46f7d715a90 \
+    --hash=sha256:195ce897c6153c0700078142cf8efe3e6454ca4cf4357499e4078dfd83396626 \
+    --hash=sha256:19a3dd5aa73cef1c99687c4fc57db016a9c17104ae1185da88ba566a5d3bebe4 \
+    --hash=sha256:1d1c7a53a6c2103925cdd6d7229f8c567379f211c869793df679f2e9f738c369 \
+    --hash=sha256:1f5883d77fd409a261abb5dc8ccbe335720d798b1de4abb3b1d47ccbbc76b53b \
+    --hash=sha256:21b82d8082f6f5e7f456ef0bd16323d08de1266efbfeb476e64b2a91d1471a4e \
+    --hash=sha256:252d099029bcbea642f2a06c4ed5046bdf8b5a8150b64afa5e027e88b106e5ee \
+    --hash=sha256:256dd4d85d9e4dc595e2bc983c980e73f62ddeb3165c58b4c3dfe78c5c8548c1 \
+    --hash=sha256:26422d45fd13551cf564c58932f7d72b4f58b93b0fcf18c35ba6be12b46bb102 \
+    --hash=sha256:2679de311c7946dde5d3b6f44941844133ff5c7cb86099c0061ab1e8901c20a8 \
+    --hash=sha256:29880d17a8eb0b5cfdfd8944b468322928059aa35f1f5fa8ff22b149ec0b42f8 \
+    --hash=sha256:2bced4061f000f7187254a02ad3433ae17eaf991747ceea2f478422590a5bba9 \
+    --hash=sha256:2e9cf9253119d8e5d111f05d71626786fd3d6193817316eab1ca088cdb8593cf \
+    --hash=sha256:2f06b7eae9dbe77fe1d644ca244dad508de8d302870a43f3c559b521270938a0 \
+    --hash=sha256:2f293479cce755c75f1697e87c409b7ae4c555c7dfecb6e988ad13abba943031 \
+    --hash=sha256:329fc3ccb63ad22d867d84c2adea759a64079a37ba4a343433b02c7a2816871e \
+    --hash=sha256:343fb4f2821043bd87095f7b08a1a181febc8e36ac64212143bbfd0a0e1bc235 \
+    --hash=sha256:3588e376b3ea2eea84976f67273d679f229e24c66dce7b82ae45aef04ff6e072 \
+    --hash=sha256:35aea775dc2bd5f54cd84a1cd2696cc3207c479cb9cf0bd346f0d343e4300ddb \
+    --hash=sha256:35fe081843b35aad20ffeccec3eeffbe637b15d14f3fb22cc1b59cd8ec17e93c \
+    --hash=sha256:36047af20e17097c3bb9476c2b7655f2f7aa51322c0ba58c07695bedf755a950 \
+    --hash=sha256:3617ac3cfd8b9888f145ad89dd6e692285834b0201c6074a5eeaad3fd4d668c2 \
+    --hash=sha256:366ec70f5547c640d3ce1985722490f23faf4eb5216a7eeba78277490e78dacb \
+    --hash=sha256:394fea06235c8543390050ed5f529187074b029fb027213f6c46ac11ab5d950e \
+    --hash=sha256:3d27167433c0d5f18dc850f07d0b3816221984fecdc405d6c157a6f0b8f8e9e6 \
+    --hash=sha256:3e5e1224c0a6a90e05843e07adfec669edebec17801c67072f51e59561d63c0b \
+    --hash=sha256:41876ee62a3dddf48ff1121ad8f0798032aa03f2fd35f21f34a4cab14f18d8d2 \
+    --hash=sha256:433c5a81eade63b47e522303bad236f59dba55ea6951746f5558355eeed8c75d \
+    --hash=sha256:4582c27e8c889d64811987b5967fbd3ae0c823fe1fd933b543d55ac20bb475fa \
+    --hash=sha256:485a0d363cafefcd2538a73c7c838daa2035f09b2c9f9b5e3133f80c6aeb84c2 \
+    --hash=sha256:494b70049a4d69aec6e8137c13af4cf8db8c9f9820a1392ac293b0dd2987a818 \
+    --hash=sha256:496846868fea80e479324862fa877f02411f2fd0f83b79ccee2607aa68b2a032 \
+    --hash=sha256:4abdc5f9ad448c1ecbfae2974b820535d6bc6e7eef63babbab3d81cf46968c71 \
+    --hash=sha256:4b599739b93b2cbeded49645ae3c8d1405c29ddfbceac1545c87a3f9580a9e96 \
+    --hash=sha256:4bea7f8ebe90bbd7f0e4a2de42ca6924ba23e3e76418c408ff82f1d46fabd687 \
+    --hash=sha256:4c4fb141a727957c93edfe5c32a26ceb6b5f6461d67146e2d39f51e16170bea8 \
+    --hash=sha256:4c9548dc78002099910abaebc0a72ac58b7d30931869e0351c09b507dff4ece3 \
+    --hash=sha256:4d26f14f041e83dd8edfd61f4cd4fa7285d31798b5bf1f28e70c367ba6c41d61 \
+    --hash=sha256:4f298bdadb8f0b9e5672877f647d1be9373ef5320c9e2f049795e26cad28b6a9 \
+    --hash=sha256:52ec005752a56ae79547a05c0139ca2501a0c866390b6115008456b9f0e7cde1 \
+    --hash=sha256:55261ac0d2941c42f196dd576f543d87a8ee03cd6f5e30dfb4d807b2e3b9121a \
+    --hash=sha256:56490c595a28b1bb27dfc583e816152a9767721ef58b2c03b13f954d2f707420 \
+    --hash=sha256:58d3e12c88e0950bca850ae1f7c256055c097639c2edb9eb123af9807d8b15e4 \
+    --hash=sha256:58d4aa13a59c969dbfdf9e6a9560e242cbfd9e8a8f50c2747714df1a423adf65 \
+    --hash=sha256:59171c6e45bf07d0d5cab3b0bf81d945035530f6873398b3b531c31184d46663 \
+    --hash=sha256:5b6d1386bf0096d26d3a863dc0a487a5b4eb9aa93cf5ba69683d29dde6b9d60f \
+    --hash=sha256:5c0ea61a470e070686aa30892fed79e297d2c8d0ab46b8bcdf027d38c51da591 \
+    --hash=sha256:5c84bec0ab5ae0c64bfe73a7d2adcb5ce73b467523fc27fd6a28ab2aa6cbe35a \
+    --hash=sha256:5ca0555312ae2fe82715cada7fac375530c2f3349e1eaa1bcb33d0283ac79a18 \
+    --hash=sha256:5d8531a6569d025f68e2321e7638fb7978f23db58e5f69f56913837aae03816e \
+    --hash=sha256:5e2d0e146dcb57034f8b97dc58d2d512cb90aba253960ce449f695fec6a82c6f \
+    --hash=sha256:5fc45d653ea8c9a20479167e11d4a0f8cb2fa3470737ab6f9c827532313187b7 \
+    --hash=sha256:6117b84ea48435e5356dc737f5121485c30920ba43375fa7b434fd753df0eac3 \
+    --hash=sha256:6199d5606e2bbf2b096cf64d03f8b6790c91081d5ac866b8e7bb6422738cc60c \
+    --hash=sha256:62b55f6722735a6c472f88361cde6640608773d9443cebdbb51abf436a1fcdd3 \
+    --hash=sha256:687c9ca3035544b113bea2055e180af96fb63c0c476e22a9180f51925186e7b7 \
+    --hash=sha256:6b7430cf5728e68f6c462254009a6ef4086e1bea43cf2f57aa9c55fb4f50ff96 \
+    --hash=sha256:6ba32c4d2abf1d2fe7cf27d280f4cca5664233b0f885549c7761719eb977f486 \
+    --hash=sha256:6c9cdde8becb25a7fde49924511aa2644d6f8081cc8df8e9452724303348d8e3 \
+    --hash=sha256:6df0ec430f9a831772c23ca5a224cba36517a58a84bb32c32bb59a9fa67c47f6 \
+    --hash=sha256:6e2912d4babbc65196ac13c2f53468dc57fb8b9c25ef913e8c59ddf7c6dc0e1b \
+    --hash=sha256:6e5e4d73d588ca5ed09df1b7dcd1b203d1df3c542e3f50d126c947d432b10731 \
+    --hash=sha256:70055ff39b97c99e7ae40ea3e393fb62aa2e44dbd9b29f8d14f42fb0025c3959 \
+    --hash=sha256:706bfd38730a5ac7a365793269a00f4e988178cec121391f4248d84ad8c972e9 \
+    --hash=sha256:7235dc28fc6dd9d832ac7c7bce95367dedb85929f17368a0c2bee1e080b9acbf \
+    --hash=sha256:774d157f112367ff4abd29019f38f023c24e00e56edc7829c20e358a5a913ad8 \
+    --hash=sha256:77efcff2b23071c349402ac1066667a3d011f62398d81408c9b88ad991747c9e \
+    --hash=sha256:789b8982559ae28dad2356519f841655756cdcd96616410590ae0b17454ee64f \
+    --hash=sha256:7ac76cf9afd34929d76eb7fcb63be476a4853d8a96f0dcf2d0db68a0cbdf9885 \
+    --hash=sha256:7c0c10730342b0c9b35dd1d619beb8214e520bd96a1f870f452680b238aab3e0 \
+    --hash=sha256:823f82903d189af463d7df250ef1f7f696f3cee08cc8d91deb565e8d425f6506 \
+    --hash=sha256:838648accb3a7fd9803fd45c87bce8509648eb0c11bc34e216141300977244f2 \
+    --hash=sha256:854066be00447fa8de2ccbbe893e2ffc4b123ef16d897af794c1e18bd4a714b0 \
+    --hash=sha256:85d5855daafc240cc045c026d7a15fd198a09b0fc8ff6f5ecbb5297b509cb11e \
+    --hash=sha256:85de3134b5379856e323ba37c19c9256d39425f7b76a63af52b09fb4664c2e8f \
+    --hash=sha256:87e4f41d375c0b9be2fb5251aee4b8a689169e134535aed81bf085c3b647451e \
+    --hash=sha256:88ca277405c2d3b71c4e1c2ee0e7966e807bcba86a69d11e19ba199d18ae4491 \
+    --hash=sha256:88e85ab89cb822c1e635f51d6d32e488f94e002e70e2f492bdb8b945543f345a \
+    --hash=sha256:8ac8c94b6539074e0f40899301273ac8402b9b3e01c7b7ba269ff30340aaaf20 \
+    --hash=sha256:8fe532b3c966d1fb794e0698e4589d0444017ae77fc0b31edea13c0e35bcc449 \
+    --hash=sha256:9085f87b0e38a2b92b8923059b4e8789fe40d9279712d15dcc670048d77079af \
+    --hash=sha256:90b7481fb62fbe172c558bc6fd1c4c98d82004a54a7551f20e11ac9bf0b8708c \
+    --hash=sha256:92caef967d287a407085d61176fce4012b1dd62daed4eb6d5ceb26d3d2538712 \
+    --hash=sha256:9362dd90aa7dab48c0054a21187791ccf05473f7dba5d92b8033ae62164675e7 \
+    --hash=sha256:94d78ecec2605a8d0398b0f365d5f12a63248438516f5dac536a5eff7337df4a \
+    --hash=sha256:94fbf1c0c6cc0d3d5e50f9a9313a8cdca90dd696d34b381cd1704f8c9e939f20 \
+    --hash=sha256:950f23cb393f85543777b0433f082cddd25b51ab398eac7971146495679efe5f \
+    --hash=sha256:96eefc178f8636b9c760c5829345307fd81cfae9ab1e80997dbddeb0f54ee9a3 \
+    --hash=sha256:96fef3e886d6a9874b14f27fc193fbdc69d5d8035783d86aa4e1cea594e695f9 \
+    --hash=sha256:977cdbd483a9cff38179bea4fd754289a6f2195c7abd414aba85410b3e66cc5e \
+    --hash=sha256:978eab16f55b4ab2c2a745be9a0a840bf8f09a7f227d9c76eb30214d078865a5 \
+    --hash=sha256:994e883d17c559cdfd38c84003c8b27d25424a1077272a17e7cd27bfe0bf57b2 \
+    --hash=sha256:9ac4444d8d4fd4c4bd08bf451ed3167aa9e7ec6cdb41b648794f1d1103652e36 \
+    --hash=sha256:9b5db6052055d34d41230fb78d7c439c23dc536a9896f6cb039e8dd92cfc1263 \
+    --hash=sha256:9d9a0dc7cbe9bec24c3f767c9122c41fe5a1bc43f47cd099d00d393e09769de4 \
+    --hash=sha256:9dbdd9205662134957cf0c324f639bdc5031c0ca056e2369e238db75187c0f11 \
+    --hash=sha256:9eea3ab2597a5e65fe65296e2d6a84570845a6b55532d90333d740d48bbc850a \
+    --hash=sha256:a2028475ba855475b8b4d3cfeb4994269c967aea8b9892dfba907f4263a863a3 \
+    --hash=sha256:a3a370082ce34d0612f421e15fe011c53bb1feff21a26d06ad4fb244dab5a375 \
+    --hash=sha256:a545775cfe815855ea32d7c27731d79da358ef2055b4a25830231b1622dd18aa \
+    --hash=sha256:a5cbd90ecf0fc62e64726917ad083b73001f0563657a87ec3c0b504e277dc90d \
+    --hash=sha256:a6d095662e73e74f0a49988e0593373e243e3a52e27bfeea0a859e88acf4a0f5 \
+    --hash=sha256:a6dac12ff6b846103483683f60c5f8fee205121adc58ffd87e90a90a3af69e99 \
+    --hash=sha256:a951ad59cad9145664a730d3036b40b844e74d2d3683da40111463cd3a83845d \
+    --hash=sha256:aa1099b956fb795e686d073568f6dc002a0bb89765ea6d5b055dd7d9bf1b116c \
+    --hash=sha256:aa2bb0b37202dca27175591f761108b5d34096ade1191ffe4808bdf6b1571488 \
+    --hash=sha256:aae2ee51122d3ae968a3837d97dc24a0aeebb0dea23694422cd172bd30017cd6 \
+    --hash=sha256:ab743e9bc90c1f73552ec33e10e3331315acd2c397b36065b591b0181de533cc \
+    --hash=sha256:ac00177c4831ffa650f8609e4bdddd5fe09c03b1c0c47acece7e6ea20421598b \
+    --hash=sha256:ac13b004224fb341e1e25a1ed5e19d32f57cdb2a403e01f003b46f051a550f6f \
+    --hash=sha256:acaf604462bf330b0d07e7a07c1d6e4adac79e5fb13e9c5140590542cafacc00 \
+    --hash=sha256:ae31a1a1db2ee6cc2942fccaf695c934bc7f3db9f2133a3fef1f367cf1a4ab10 \
+    --hash=sha256:ae4a097991662cd4fff0ddc74e0fe7874f82e00042fa0ea00855645ed0c79598 \
+    --hash=sha256:aea996a6aba25260827c9ea511d1addfde2da9eb686ac961838509086188b7e6 \
+    --hash=sha256:b39b69b347e5e47a3b5b8cfc005c68c1ba347474e3960236c4944a8ecd174962 \
+    --hash=sha256:b54e7e13267d49ffbfe68e25b3cbd774dab38fa37238f71265e91b36146eb21c \
+    --hash=sha256:b9af956078716df40d985fb0dfeb2c2120c5ca92ba4ff4b388acfd01cdc14d08 \
+    --hash=sha256:ba2f37ee79e6338845261a3c5b1784e5d1acdff2c0785b284f1b633033d136ab \
+    --hash=sha256:ba501e667c17d8411f98e67a022d9604ef179aff0e459b7e292c796837c13573 \
+    --hash=sha256:baf3775a2635e5a11fbd5e4e64ee69c7e86875d224a5c72aca4c141064589a90 \
+    --hash=sha256:bb57753e36e4855b8ca375069482250a6246372331a3e4f3407eaebb007443f5 \
+    --hash=sha256:bd6c173f04743d483881bffa1478d5a4624475b8cd1d2194956a75548e191c18 \
+    --hash=sha256:be47f99644b208bff7766314013f9acf57b056b04191d570d68ad14022cf5b1d \
+    --hash=sha256:c010f5581d9c612804cc59fcf7b524b707fbcb72828551237ab545bb5c7034af \
+    --hash=sha256:c1dcc36dcb96abc02236e182d17e0f71430152a6c2c7447421da2d2dc144edea \
+    --hash=sha256:c428c6c31eb5f4277d7f8eccaf767fbd548ddd5ce3c8b4f4cbbfab3d96b5904c \
+    --hash=sha256:c658c50ac0c98cd755a2dd50b7977d3bca7df401dcc47fbdfa87db53ef7d4e8b \
+    --hash=sha256:c71fb0d56c920c269cd3e2e3fe7c610e3f1fdb21a6ce60efa6430ff63676cea6 \
+    --hash=sha256:c7b742bf31c88566b4bb6335a7f393bb322e580b6bb98df7bd0c25e6e3519ce8 \
+    --hash=sha256:cc0329df4caaceb950d2f580b5ac716a377f7059624a0bafaeaf8a218c6ed774 \
+    --hash=sha256:cc5d36d96478aa9c60654bd932525bf32964c62a7281eafdf16d85003a8d6004 \
+    --hash=sha256:ce854f5f478050ade5a238731c4ca985a7d3b3cb53ff600a9b5c3b689b5f0a7a \
+    --hash=sha256:ced3fdd71aaa83ce593746c2edb42b7a59cb4c19c8b5c407781c72e493aae55a \
+    --hash=sha256:cee5dd7c6fb5dd52a0fe2a740f9bc6e3593f5f8b1788bde49de02086f30182b2 \
+    --hash=sha256:cfa1c0cc3a8f9f53f1243a5a99ac36fd003880199383b37672e86ddda9cb07e2 \
+    --hash=sha256:d1ee1e296209fdce05b81b663250eefa02213a2da7b41bf26f7829b8ba3545aa \
+    --hash=sha256:d59b75732e9b6f27388e10c14b0259cc5f2e48c78627d185e6a177b58ad3cffe \
+    --hash=sha256:d63600d620ad0064c3a748b950ac5ea38a80190e5498532efefa4b7b3f1da1f3 \
+    --hash=sha256:dd732602a7009217f658d5863d12d79d373a4de0eebc111094bcdd3bb8e0a6cc \
+    --hash=sha256:e06efa066f7dbadbc84ebc126a97c452a6451dfcf589d89d788484949e1cf795 \
+    --hash=sha256:e199fb99720074809a7720f1c0b4d919eea8b87e88713e0f8f602f7bef543d9d \
+    --hash=sha256:e4b018dc5a0eee4676e38fe84a47a427816c590b93b55d9025274ec4d6ffc2dc \
+    --hash=sha256:e6621fb2a4988d6e53eedc455e5903e2679f3967b8acb3d639f1b63c14a2e893 \
+    --hash=sha256:e71c909f353863b2b89c83de2ebed71ea6d0df8a6ef65a128193c5e650766bef \
+    --hash=sha256:e90251c0c7bdd54a100a0dce3c07b7e637278c93af29dbf78ebb89a58c4bac7d \
+    --hash=sha256:e9fbdce1e47394b09bc9f26ab117dfc8d6491977a11d86f592bb42c779db2fda \
+    --hash=sha256:eb12fb2ba69ffa05f8695f61c69e591dc4b4a12ac3757ac8af8adb259bf56d17 \
+    --hash=sha256:eda059b6bc8bc0812d626fd91a7ce01bf583df0a61296eff390fd94141a34e30 \
+    --hash=sha256:f03ac127268b43ef4fe9e6ab6794a6794b49485a0cc0c1db79876d2f33f75bc7 \
+    --hash=sha256:f298e218441525d3794428b4c8b8fb8662c6d3ea79925d4807ee6b9a96a3bca5 \
+    --hash=sha256:f5542f9b941279d82d41eb0aa9f98eba36fe4df5c7086c651df7944935b37182 \
+    --hash=sha256:f6f7deae3feb4edfa2efaf7c574fe88cbf055038a6abdb40188e4fff66d5699f \
+    --hash=sha256:f9b1e28d0e8dbfa858abdba91d6b547beaf2df1a59bec6da6faae7b96a4991a9 \
+    --hash=sha256:f9f8405c2c758532c74fed975dbee57be1f31a6e865c031870c79a6ed3212ada \
+    --hash=sha256:fa48b1b63d639f9483e0633e092f5851e2348c352f1f9bb6c8182f87884ef876 \
+    --hash=sha256:fb78f6e7fcd8ad785d28cd577168bc1aaee827b25bb8755638f694794ea98f0a \
+    --hash=sha256:fbc597639158fd7c14d55e808718848319540f51b0e6746e3eefa59723a4a348 \
+    --hash=sha256:fce8cbd4997efeb450bd298b54f755dcdff18d496f7a5ddbb4867c6d7c88fdc3 \
+    --hash=sha256:fd0350afdc3aabd5576f60ea109228bd5538139713c7b094c5cd27c73a98bc6f \
+    --hash=sha256:fd0a274c0e5f9a21565cd9d3dd749b61f96b7aa1e20a93aa1ba4029518f2e5c0 \
+    --hash=sha256:fdb8a068947befafba9952162645dc2fecaeb400e64584829ed5e9b2fbe21a7f
+    # via requests
+cryptography==50.0.1 \
+    --hash=sha256:01f41478cf33fc605a6a089cd56d28b45c6c0b45a1928b61797f2621a04bac71 \
+    --hash=sha256:05ba322c4da95b262a212c345af888ef2c37c88c0509756ea00a0e6d68850f23 \
+    --hash=sha256:16c5ecd954b3330ebfb6605eca4fd952da8bef376551d5cc264534e3770a9ee6 \
+    --hash=sha256:2a93d05e34d5f67fba6f891fe85d929999baa7195e853923ea6d7576c9e68c5e \
+    --hash=sha256:2b34d76a652ea2b6faf777c35df230c5637842cd904e04f16230c3f9f03e4361 \
+    --hash=sha256:2ebbfb0f1fed745e91796e3e1080a1440423fdae8ece1b995a1d80883a409054 \
+    --hash=sha256:30a125032e5642a21ff816e021152bd4e7e94f03eff3f4b7fca41cd22bc3110f \
+    --hash=sha256:330fbb252391c596f1ae42c5754449dc924e6ad012dca8efe0d703f9f2d12ec6 \
+    --hash=sha256:359e62deae718bce96170e223fdcb6357e4fbd3bb7a3a75f4430763532560e49 \
+    --hash=sha256:407fe2b6db00939c05c0e945e9914238f2f0a430974839429dafc82b1ee6bee5 \
+    --hash=sha256:42be3bb70596b3abe4ac097b75be223e8b3ab614a0e5de068e3dcc54d71d6149 \
+    --hash=sha256:4c4188f7c0cf655be5c06342b817ed0f9595b69ffa2b12026e5353eed29dea88 \
+    --hash=sha256:51593d180cf6d179bde5c5d065bed81386b1f381656ae7d042b7ffc87a9895ad \
+    --hash=sha256:51afcfceb15597cf2635068e4ac9a56b2abde622edde17f37d85fd7b5306497a \
+    --hash=sha256:53e279950892dc102c6b4e52af03ae5ea92fac572a1ddab78ca73a997f62b69f \
+    --hash=sha256:55d16b1ef3ee0958d893a977b19777887e546c9954ea81b200c3301a864013f2 \
+    --hash=sha256:5dd9bda1c12b4162f6ff568eeb5e0ff956c28d14406e875cfe8a63a2d414ff20 \
+    --hash=sha256:5fe002589592ed749ce77fe0695fcbd3500dd61d7d6db5858a7544c612fa8e45 \
+    --hash=sha256:5fe939deeb161024a6be98229c953b6591fef1f41214497a78fe793a244c017f \
+    --hash=sha256:693c99b49bd37d0d096e4334c10232c77248c415b98d35236094cdf96d57258b \
+    --hash=sha256:76de83fbd91ac49c0feaaa983d0748fd7a53176afac5fb3bf7478d244f0eb527 \
+    --hash=sha256:79bf008d1f9af6071c797ad133e39915dfee7614f18f18f4db9072eb715064a3 \
+    --hash=sha256:804728ce710890870f3aaa344b2e161172d258d768ac139d02cfd9092d0d94e6 \
+    --hash=sha256:8921d58f426793c5f1b47f0b59575780de9a095214958d0eb37d909593db8367 \
+    --hash=sha256:8df2de9102026855887e4587084f6eabd80ed0f345b8ad8a7ac27ab9bf4723e0 \
+    --hash=sha256:9cb3cb952cf5a8abd50c782a98a89d71699715e802fe349704b47f2425b42a94 \
+    --hash=sha256:9dde0a357190eb3b1da1bb9ab750e9c85cba82ca5977aa0836cbb94e92611239 \
+    --hash=sha256:9ebcdd5519be9b652a46f507817a74591774fc3d6923ac364e4dfa64e36b291b \
+    --hash=sha256:a0b1a59e3a089064a0ec309e9428c8e3ae4e161419d20ac33600767e83fc658a \
+    --hash=sha256:a255449073358275b64b67d3f595f268bbef70e72b6edb65e0c70c735bf739c9 \
+    --hash=sha256:a8f40ea47330e71b594a7e246898f93177c259490c63183dbaf9e571d71ed9a5 \
+    --hash=sha256:ac02b07824d4d1001bd4367599f839c19cb171924c796e52c23508ac14c2c0cc \
+    --hash=sha256:aed8db4f6d71c51efb89530e12d9464e7bf2923d46c3205dc794a2a93f8c0648 \
+    --hash=sha256:b8f852c65863251b9e3a1b8c150ce21e59b522dbb6a7d4bc80e680d38388e986 \
+    --hash=sha256:be224a65493ec5b74a158ff22a5522ce4a5ca1e543c647a3a4730d4a09e5f959 \
+    --hash=sha256:ca83d00d9e69cd5eb63f2e69c3a5a59e0cecae5ae14c6ae0b35830fe3b37bad0 \
+    --hash=sha256:cbf74a81765ee67413503ca6e26dcc4f6f5a519822436cc0a1b97aab6c1b8a17 \
+    --hash=sha256:d63ae8f6481fec907ac0f588eee8a90aefde112c633131fe540e5711ddbb5a4e \
+    --hash=sha256:e22dfed744bd4002e909464cb23d2f0b05c6f3113a79ef2e9864a53db737c733 \
+    --hash=sha256:e2ca8fd1b6b4b82a1c4cb02841d0837e3c12336c2e24b520ab8ab3b969733d8f \
+    --hash=sha256:e74591e283fe6eb956416c929eb58262a719fe0311fd9054c62c3350ed8760d8 \
+    --hash=sha256:f74455bb086a85d5e81246412602aaa97ed095e504cd40dd261ef50be42205bf \
+    --hash=sha256:fb4b9672d389c738b175c4166e78310f8a70358886aacd9173ee03a85ffdc671 \
+    --hash=sha256:fc3ed7ebd2a8c96f5b166de0ab9b624996bef3b07bbeb19364dfb78222c22c80 \
+    --hash=sha256:fd3718b960d0b5dd213cdf03f3bcb7000e69dda0de8b956061947ff6bcff5558 \
+    --hash=sha256:ff838d62ec1bfce4f9ba7fa16f4a7b554cd8d0c299e6be37502161a660c84eef
+    # via secretstorage
+docutils==0.23 \
+    --hash=sha256:25d013af9bf23bc1c7b2b093dff4208166c53a94786c9e447808335ef1185fea \
+    --hash=sha256:746f5060322511280a1e50eb76846ed6bf2342984b2ac04dc42caa1a8d78799e
+    # via readme-renderer
+id==1.6.1 \
+    --hash=sha256:d0732d624fb46fd4e7bc4e5152f00214450953b9e772c182c1c22964def1a069 \
+    --hash=sha256:f5ec41ed2629a508f5d0988eda142e190c9c6da971100612c4de9ad9f9b237ca
+    # via twine
+idna==3.19 \
+    --hash=sha256:5e0811a4383b21dc5838069f801c4fb62113b7447663d2530d2bd6e77b49bf15 \
+    --hash=sha256:815e7be7a7806d54abb586dc943addc79e8b2ee16915059658cbeff4b1b43bf4
+    # via requests
+importlib-metadata==9.0.1 \
+    --hash=sha256:ab830580bc0ef3db61ce8fae716389e5462b67e033018bab6d8f80ef17172f99 \
+    --hash=sha256:bba5600596a7e21f3eef53281cf28d6a5195634d2f2b78ff9501a3272c6eaab0
+    # via keyring
+jaraco-classes==3.4.0 \
+    --hash=sha256:47a024b51d0239c0dd8c8540c6c7f484be3b8fcf0b2d85c13825780d3b3f3acd \
+    --hash=sha256:f662826b6bed8cace05e7ff873ce0f9283b5c924470fe664fff1c2f00f581790
+    # via keyring
+jaraco-context==6.1.2 \
+    --hash=sha256:bf8150b79a2d5d91ae48629d8b427a8f7ba0e1097dd6202a9059f29a36379535 \
+    --hash=sha256:f1a6c9d391e661cc5b8d39861ff077a7dc24dc23833ccee564b234b81c82dfe3
+    # via keyring
+jaraco-functools==4.6.0 \
+    --hash=sha256:880c577ec9720b3a052d5bc611fb9f2269b3d87902ef42440df443b88e443280 \
+    --hash=sha256:99e3dc0060c5cbe8fcd1cdb36258e2a65ca40f1566b2033b12abb1bb44dd3c30
+    # via keyring
+jeepney==0.9.0 \
+    --hash=sha256:97e5714520c16fc0a45695e5365a2e11b81ea79bba796e26f9f1d178cb182683 \
+    --hash=sha256:cf0e9e845622b81e4a28df94c40345400256ec608d0e55bb8a3feaa9163f5732
+    # via
+    #   keyring
+    #   secretstorage
+keyring==25.7.0 \
+    --hash=sha256:be4a0b195f149690c166e850609a477c532ddbfbaed96a404d4e43f8d5e2689f \
+    --hash=sha256:fe01bd85eb3f8fb3dd0405defdeac9a5b4f6f0439edbb3149577f244a2e8245b
+    # via twine
+markdown-it-py==4.2.0 \
+    --hash=sha256:04a21681d6fbb623de53f6f364d352309d4094dd4194040a10fd51833e418d49 \
+    --hash=sha256:9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a
+    # via rich
+mdurl==0.1.2 \
+    --hash=sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8 \
+    --hash=sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba
+    # via markdown-it-py
+more-itertools==11.1.0 \
+    --hash=sha256:48e8f4d9e7e5878571ecf6f2b4e57634f93cd474cc8cfbd2376f2d11b396e30d \
+    --hash=sha256:4b65538ae22f6fed0ce4874efd317463a7489796a0939fa66824dd542125a192
+    # via
+    #   jaraco-classes
+    #   jaraco-functools
+nh3==0.3.7 \
+    --hash=sha256:157ec1eb7a62f3d9a7badb8d82d89aa810e3e24e097eedfa481a25d0c8a99877 \
+    --hash=sha256:15f5fbf090f5c88d61c820e1fc1fceecb6520cca9fe85649c06b57ef9dc9ff62 \
+    --hash=sha256:18f4278ecd157d43cb35acd5aae9f35cfa79f546b4922bd86536adc0f6312102 \
+    --hash=sha256:19f288c938ec6eef1f5d2c6cab47838e71fef8097e1c1233802be5a6230ba086 \
+    --hash=sha256:4968fe8d2db97c6f047659bf46a449fd8ec377f44ebf3e0a1b96c0d3a333ae32 \
+    --hash=sha256:5ffdfcb9a686ffb12765376bcfb6b5b55728516d3c0ee317d29982381ded3df8 \
+    --hash=sha256:614dac4a4c36ad084e78447d16fe898dedd762e354a7ab9cda2984e82f67883d \
+    --hash=sha256:618e3059caf41ccdf5dcccb3fa9df4cf6e4efe23d1382a8bbfca272a8a4f8bfc \
+    --hash=sha256:6698a822132beedab80f131c08d8d0ac5a178ddeb488d02ca4b67716ecfac7af \
+    --hash=sha256:6c3aa50eb26e9228238271db9f983cbc3b006dfbfeca2d4dc34c33ddc6ac5ea5 \
+    --hash=sha256:6e4280115d44c3b278eef712a86748c1a723105cd79feec46952383117ab4e59 \
+    --hash=sha256:70f5ac8626e899a4bab0ef74ca2f5bd602f49c7b739e6e5026b4afc6d63dac42 \
+    --hash=sha256:71860d01c16f4d8c72e334e0674beb2b0899dbd0bf760de18932ef4390303848 \
+    --hash=sha256:808def0c8c07843e6e50dc84f532457bfa2cfd17417b219a5d9e7c773709331a \
+    --hash=sha256:874b7d67a067bd29a59223f6270fc30da4edd8e6d87fd219fc93bcbaa662c946 \
+    --hash=sha256:91a4dab4e94d9fc54b9f67b1adfb23e81fab7ab43f33c3b8c97be9aa38f789ba \
+    --hash=sha256:94fd6e59553fbb9ffd8ba71bbd5a54e3126ba01799a097ae30d5341d750bc6ac \
+    --hash=sha256:9b7279d43323a25225df23576af6594a16693f61431170848b8b2ac21ad4f174 \
+    --hash=sha256:bc42bb1193c1e28a1e74c2cabaca178e118a7103e8832699fef8a2b3e2496493 \
+    --hash=sha256:be53a4825585f701955cb9baf49f478f56eb81e20294329fe4bc689dd5dd81fa \
+    --hash=sha256:d56e76bd3cadb09b6b0cef364850811663734b348a25f5f587a2819c495367bd \
+    --hash=sha256:de2b2aab32ea303405debefdcfc58043d3e635fa3f67b9eb140d2b0e0c0d2563 \
+    --hash=sha256:e8fd1ab205258b29254f72db377d99e2c96aa7653ef3b015ccab0420b094b506 \
+    --hash=sha256:eae64328e46a25785535afcb6885b6f182ecaf5ee8c88f8c075422db8aacc65b \
+    --hash=sha256:f04b7d333b27f13ca439da3cf1c75c2fba34f104969f6ce4ac8e7079699c2f4a \
+    --hash=sha256:f266d3f1b3647449923a8e406524632220dd5d8b647078dfe45b885d33d10479 \
+    --hash=sha256:fd4a70efb45d5372174f718878eb7a35c12677626a63b2f103b23b833457dcac
+    # via readme-renderer
+packaging==26.3 \
+    --hash=sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79 \
+    --hash=sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c
+    # via twine
+pycparser==3.0 \
+    --hash=sha256:600f49d217304a5902ac3c37e1281c9fe94e4d0489de643a9504c5cdfdfc6b29 \
+    --hash=sha256:b727414169a36b7d524c1c3e31839a521725078d7b2ff038656844266160a992
+    # via cffi
+pygments==2.21.0 \
+    --hash=sha256:2363c69b61c4a97c838da3b130dcd6468f4848992b21a82f2a63ec34377137d9 \
+    --hash=sha256:610ca751c9bc2492b38eb9a38a7fbc93edbbb2d7182edaf34e66ae493dee5c8c
+    # via
+    #   readme-renderer
+    #   rich
+readme-renderer==46.0 \
+    --hash=sha256:af3e964914f6310a33ff67b72a4bdd940bed8d7c3bdecd2d14f40edf284bfe90 \
+    --hash=sha256:d0dae1f74bb273b534770cb4cccb6bb78735540afdb03c2146f4e19dcd412560
+    # via twine
+requests==2.34.2 \
+    --hash=sha256:2a0d60c172f83ac6ab31e4554906c0f3b3588d37b5cb939b1c061f4907e278e0 \
+    --hash=sha256:f288924cae4e29463698d6d60bc6a4da69c89185ad1e0bcc4104f584e960b9ed
+    # via
+    #   requests-toolbelt
+    #   twine
+requests-toolbelt==1.0.0 \
+    --hash=sha256:7681a0a3d047012b5bdc0ee37d7f8f07ebe76ab08caeccfc3921ce23c88d5bc6 \
+    --hash=sha256:cccfdd665f0a24fcf4726e690f65639d272bb0637b9b92dfd91a5568ccf6bd06
+    # via twine
+rfc3986==2.0.0 \
+    --hash=sha256:50b1502b60e289cb37883f3dfd34532b8873c7de9f49bb546641ce9cbd256ebd \
+    --hash=sha256:97aacf9dbd4bfd829baad6e6309fa6573aaf1be3f6fa735c8ab05e46cecb261c
+    # via twine
+rich==15.0.0 \
+    --hash=sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb \
+    --hash=sha256:edd07a4824c6b40189fb7ac9bc4c52536e9780fbbfbddf6f1e2502c31b068c36
+    # via twine
+secretstorage==3.5.0 \
+    --hash=sha256:0ce65888c0725fcb2c5bc0fdb8e5438eece02c523557ea40ce0703c266248137 \
+    --hash=sha256:f04b8e4689cbce351744d5537bf6b1329c6fc68f91fa666f60a380edddcd11be
+    # via keyring
+twine==7.0.0 \
+    --hash=sha256:85cdb29c518efef867360ae4acd4b0dfd61c8654a22fca08e6f8539f05022177 \
+    --hash=sha256:b854164df26db268af05f49aa5c0344b10e27a494343ff05b1e0bad3b135f5a7
+    # via -r .github/requirements/twine.in
+urllib3==2.7.0 \
+    --hash=sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c \
+    --hash=sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897
+    # via
+    #   id
+    #   requests
+    #   twine
+zipp==4.1.0 \
+    --hash=sha256:25ad4e16390cd314347dd8f1de67a2ac538ae658ed4ab9db16029c07c188e97f \
+    --hash=sha256:4cb57381f544315db7688e976e922a2b18cdb513d21cc194eb42232ba2a3e602
+    # via importlib-metadata

.github/requirements/uv-tool.in

@@ -0,0 +1 @@
+uv==0.12.1

.github/requirements/uv-tool.txt

@@ -0,0 +1,23 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile .github/requirements/uv-tool.in --generate-hashes --python-version 3.11 --python-platform linux -o .github/requirements/uv-tool.txt
+uv==0.12.1 \
+    --hash=sha256:04290ea4001dca31ac8a8324113a4930dccad69ce35dbf6eaae307d54880890d \
+    --hash=sha256:153ec0959a15397514438aefc1d7cd04235f335dd6bb53ea0f9e6e82c5a49f03 \
+    --hash=sha256:173ee216f17d89fc39f65339d311a53584fc7de4918d27c0f3c7edafabc6b54d \
+    --hash=sha256:1de49d9b04438f1ad2f41a1441dbbe19e230b94fca56d632818cfaed69e03bfc \
+    --hash=sha256:1e8fd95fe98768e29436ad57f9ef7b68dc294b7b9862ef63396af8b15ab85e6c \
+    --hash=sha256:27211df9b277f440dea438a4e525ba40250fb721ad39b8927eefc2d91f9aea15 \
+    --hash=sha256:29399e1e73b67ed24abe82bc971aa4eb8419c4de804784290f39cf681f0b51ce \
+    --hash=sha256:2e9b0b86e180abc5968b979c6e25203b32e85969abb5083ee1e8b88a5aa98a76 \
+    --hash=sha256:3bd5db002adc763aa8d277f5b44f8d6e3fd82d20f2e51225b0bbdae1badc7259 \
+    --hash=sha256:41b8fc2335f682312a1ca39a7b4abfd6af800992065c663582ca3e4d51cf9258 \
+    --hash=sha256:5bd04849dd5346517cc4e57b4b3aa0b01c67c423878260c04f5893a038fe25b6 \
+    --hash=sha256:6f7e72543264d2420ebb2ddc84696a751af2d6c5910046b7666589118f47292b \
+    --hash=sha256:71f86410264c69a3e8acd18171897dd8ab1a13350cf40f718e4def5db2b724be \
+    --hash=sha256:76d87de420213ca92fa403e87023c4c7c6956c6726c6b96d91c42cfe620173a3 \
+    --hash=sha256:9331dda0dc4990512c232f86e1d3a7b83c13f459777fcc2bd46030911b40eaaa \
+    --hash=sha256:b255ac23958e45f39f9c7a4cd65890df5ef46f539a3b14de03bd296bbba9cb60 \
+    --hash=sha256:bd02f2da212e6a983115dc64a6fc94e9256c2d60e056d6b669de0a6025aaec05 \
+    --hash=sha256:e35e0030480a8c3bf8ecd87ae4a6f6a224009e15e96a6fbb3634ac11ab75d582 \
+    --hash=sha256:ead7ad064f291a5df358c3ffa8ffab347a32bd5a75a6a068ca22254c2539a829
+    # via -r .github/requirements/uv-tool.in

.github/workflows/benchmark.yml

@@ -28,11 +28,29 @@ jobs:
 
           BENCHMARK_REAL_LIBS: "1"
         run: |
-          python -m pip install --upgrade pip
-          pip install -e .
+          pip install -r .github/requirements/bootstrap.txt --require-hashes
+          # --no-deps + a hash-pinned install of the same base dependency set
+          # (rather than a bare `pip install -e .`) so every fetched package
+          # is hash-verified (Scorecard Pinned-Dependencies); the local
+          # editable install itself has nothing to hash.
+          #
+          # --no-deps only skips *runtime* dependency resolution - `-e .`
+          # still does a PEP 517 build, which by default creates an isolated
+          # build env and fetches [build-system] requires (setuptools,
+          # wheel) completely outside any hash checking. Install
+          # pep517-build.txt (pins that exact build-system.requires) first
+          # and pass --no-build-isolation so pip reuses those hash-verified
+          # copies instead of fetching its own.
+          pip install -r .github/requirements/pep517-build.txt --require-hashes
+          pip install --no-deps --no-build-isolation -e .
+          pip install -r .github/requirements/base-deps.txt --require-hashes
+          # NOTE: benchmarks/ does not currently exist in this repo, so this
+          # step and the run below it fail on any real invocation - pre-existing,
+          # unrelated to this pinning change. Left as-is since there's nothing
+          # to hash without knowing what belongs there.
           pip install -r benchmarks/requirements.txt
           python -m spacy download en_core_web_sm
-          pip install rdflib neo4j faiss-cpu torch pyarrow pdfplumber python-pptx openpyxl lxml python-docx beautifulsoup4 chardet langdetect
+          pip install -r .github/requirements/benchmark-extra.txt --require-hashes
 
       - name: Execute Benchmarks (Real Mode)
         env:

.github/workflows/ci.yml

@@ -33,21 +33,58 @@ jobs:
       - name: Install Explorer frontend dependencies
         working-directory: explorer
         run: npm ci
+      - name: Install Playwright Chromium
+        working-directory: explorer
+        run: npx playwright install --with-deps chromium
       - name: Test Explorer frontend
         working-directory: explorer
         run: |
           npm run test:graph-store
           npm run test:graph-workspace
           npm run test:plugin-registry
+          npm run test:deterministic-e2e
       - name: Build Explorer frontend
         working-directory: explorer
         run: npm run build
+      - name: Install Explorer backend test dependencies
+        run: |
+          # Run the deterministic backend path before the all-extras CI
+          # environment is installed.  The Explorer extra supplies the
+          # production API dependencies without importing optional vector
+          # providers such as Pinecone during test collection.
+          #
+          # --no-deps + a separate hash-pinned install (rather than the old
+          # `pip install -e ".[explorer]" pytest==9.1.1`) so every fetched
+          # package is hash-verified (Scorecard Pinned-Dependencies); the
+          # local editable install itself has nothing to hash.
+          # .github/requirements/explorer-extra-py311.txt is
+          # `uv pip compile pyproject.toml --extra explorer --python-version 3.11 --constraint requirements-ci.txt --generate-hashes`
+          # - regenerate it the same way if pyproject.toml's base/explorer
+          # deps change. Resolved specifically for this job's python 3.11
+          # (see the Dockerfile's explorer-extra-py313.txt for why this
+          # can't be shared with python 3.13: audioread needs extra
+          # standard-aifc/standard-sunau hashes only on 3.13+).
+          #
+          # --no-deps only skips *runtime* dependency resolution - `-e .`
+          # still does a PEP 517 build, which by default creates an isolated
+          # build env and fetches [build-system] requires (setuptools,
+          # wheel) completely outside any hash checking. Install
+          # pep517-build.txt (pins that exact build-system.requires) first
+          # and pass --no-build-isolation so pip reuses those hash-verified
+          # copies instead of fetching its own.
+          pip install -r .github/requirements/pep517-build.txt --require-hashes
+          pip install --no-deps --no-build-isolation -e .
+          pip install -r .github/requirements/explorer-extra-py311.txt --require-hashes
+          pip install -r .github/requirements/pytest-tool.txt --require-hashes
+      - name: Test deterministic Explorer backend path
+        run: |
+          pytest -q tests/explorer/test_explorer_deterministic_rendering_e2e.py
       - name: Install pinned Python dependencies
         run: |
-          pip install -r requirements-ci.txt
+          pip install -r requirements-ci.txt --require-hashes
       - name: Verify requirements-ci.txt is up to date
         run: |
-          pip install uv==0.12.1
+          pip install -r .github/requirements/uv-tool.txt --require-hashes
           # Re-resolve with the committed file as a constraint: upstream package
           # releases must NOT fail CI (deps only change when pyproject.toml
           # changes intentionally). Compare only version lines (pkg==ver),
@@ -58,10 +95,10 @@ jobs:
           diff \
             <(grep -E '^[a-zA-Z0-9._-]+==' requirements-ci.txt | sed 's/ \\$//') \
             <(grep -E '^[a-zA-Z0-9._-]+==' /tmp/requirements-ci-check.txt)
-      - run: pip install build
-      # wheel is build-time only (not in requirements-ci.txt) — install the
-      # same pinned version [build-system] declares so --no-isolation works.
-      - run: pip install wheel==0.48.0
+      # build is a dev-time dependency; wheel is build-time only (neither is
+      # in requirements-ci.txt) — install the same pinned versions
+      # [build-system] declares so --no-isolation works below.
+      - run: pip install -r .github/requirements/build-tools.txt --require-hashes
       - name: Build package (no isolation — pinned deps)
         run: python -m build --no-isolation
       - name: Verify Explorer frontend is packaged

.github/workflows/codeql.yml

@@ -10,13 +10,15 @@ on:
 
 permissions:
   contents: read
-  security-events: write
-  actions: read
 
 jobs:
   analyze:
     name: Analyze Python
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write  # for github/codeql-action/upload-sarif below
+      actions: read           # for github/codeql-action/init's CodeQL bundle cache lookup
 
     steps:
       - name: Checkout repository
@@ -32,7 +34,7 @@ jobs:
       # meaningful state carried over from a failed attempt.
       - name: Initialize CodeQL (attempt 1)
         id: codeql-init-1
-        uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
+        uses: github/codeql-action/init@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
         continue-on-error: true
         with:
           languages: python
@@ -42,7 +44,7 @@ jobs:
       - name: Initialize CodeQL (attempt 2)
         id: codeql-init-2
         if: steps.codeql-init-1.outcome == 'failure'
-        uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
+        uses: github/codeql-action/init@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
         continue-on-error: true
         with:
           languages: python
@@ -52,17 +54,17 @@ jobs:
       - name: Initialize CodeQL (attempt 3)
         id: codeql-init-3
         if: steps.codeql-init-2.outcome == 'failure'
-        uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
+        uses: github/codeql-action/init@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
         with:
           languages: python
           queries: security-and-quality
           config-file: .github/codeql/codeql-config.yml
 
       - name: Autobuild
-        uses: github/codeql-action/autobuild@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
+        uses: github/codeql-action/autobuild@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
+        uses: github/codeql-action/analyze@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
         with:
           category: "/language:python"
           upload: false
@@ -72,7 +74,7 @@ jobs:
         # Uploads results only when Default Setup is not active.
         # If Default Setup is still enabled, this step skips gracefully
         # instead of failing the workflow with HTTP 409.
-        uses: github/codeql-action/upload-sarif@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
+        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
         with:
           sarif_file: ${{ steps.codeql.outputs.sarif-output }}
           category: "/language:python"

.github/workflows/container-scan.yml

@@ -0,0 +1,75 @@
+name: Container Security Scan
+
+on:
+  push:
+    branches: [main]
+    # Mirrors .dockerignore's opt-in list exactly - anything not listed there
+    # can't reach the build context, so it can't change the built image.
+    paths:
+      - 'Dockerfile'
+      - '.dockerignore'
+      - 'pyproject.toml'
+      - 'README.md'
+      - 'LICENSE'
+      - 'MANIFEST.in'
+      - '.github/requirements/explorer-extra-py313.txt'
+      - '.github/requirements/pep517-build.txt'
+      - 'semantica/**'
+      - 'integrations/**'
+      - 'explorer/**'
+      - '.github/workflows/container-scan.yml'
+  schedule:
+    - cron: '30 2 * * 1'  # weekly, catches new CVEs published against the base image between pushes
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write  # for github/codeql-action/upload-sarif below
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Build image
+        run: docker build -t semantica:scan .
+
+      # Run Trivy as a digest-pinned image rather than the aquasecurity/trivy-action
+      # marketplace wrapper: the aquasecurity GitHub org has an IP allow list on its
+      # API that 403s verify-action-pins.sh's live tag->SHA check from Actions-runner
+      # IPs, and this repo already treats Trivy's action pin as a known past target
+      # for tag-repointing (see the LiteLLM/Trivy 2026 incident note above). Pulling
+      # by sha256 digest from Docker Hub is immutable and verifiable independently of
+      # GitHub's API, so it sidesteps both problems at once instead of carving a skip
+      # exception into the pin verifier for an org already flagged as higher-risk.
+      #
+      # Report-only for now: this is Trivy's first run against this image, so we
+      # don't yet know the CRITICAL/HIGH baseline. Findings still land in the
+      # Security tab either way. Once triaged, add `--exit-code 1` (like
+      # Safety/Bandit-HIGH in security-scan.yml) to make it a hard gate.
+      - name: Scan image for vulnerabilities (Trivy)
+        run: |
+          docker run --rm \
+            -v /var/run/docker.sock:/var/run/docker.sock \
+            -v "$PWD:/output" \
+            aquasec/trivy@sha256:62b1e65e8869bc4b4c6aa4fa2b21595256c7c2f6018a9d9ad61caf87187c1969 \
+            image --format sarif --output /output/trivy-results.sarif \
+            --severity CRITICAL,HIGH --ignore-unfixed semantica:scan
+
+      - name: Upload Trivy SARIF
+        if: always()
+        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
+        with:
+          sarif_file: trivy-results.sarif
+          category: trivy-container
+
+      - name: Generate SBOM (Syft)
+        if: always()
+        uses: anchore/sbom-action@3ad7283483fc7af8ff2b4ea19663c2d5ca935e26 # v0.24.2
+        with:
+          image: semantica:scan
+          format: spdx-json
+          output-file: semantica-sbom.spdx.json

.github/workflows/defender-for-devops.yml

@@ -28,12 +28,14 @@ on:
 
 permissions:
   contents: read
-  security-events: write
 
 jobs:
   MSDO:
     # currently only windows-latest is supported
     runs-on: windows-latest
+    permissions:
+      contents: read
+      security-events: write  # for github/codeql-action/upload-sarif below
 
     steps:
     - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
@@ -57,7 +59,7 @@ jobs:
         # avoiding the guardian.cmd/checkov exit-code bug in the MSDO wrapper.
         tools: eslint,templateanalyzer,terrascan
     - name: Upload results to Security tab
-      uses: github/codeql-action/upload-sarif@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
+      uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
       with:
         sarif_file: ${{ steps.msdo.outputs.sarifFile }}
 
@@ -66,7 +68,7 @@ jobs:
         python-version: "3.12"
 
     - name: Install Checkov
-      run: python -m pip install checkov==3.3.1
+      run: pip install -r .github/requirements/checkov.txt --require-hashes
 
     - name: Run Checkov
       shell: pwsh
@@ -82,7 +84,7 @@ jobs:
         }
 
     - name: Upload Checkov results to Security tab
-      uses: github/codeql-action/upload-sarif@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
+      uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
       if: always()
       with:
         sarif_file: reports/checkov.sarif

.github/workflows/install-matrix.yml

@@ -0,0 +1,59 @@
+name: Install Matrix
+
+permissions:
+  contents: read
+
+on:
+  schedule:
+    - cron: '0 6 * * 1'  # weekly, catches upstream dependency breakage between releases
+  workflow_run:
+    # The Release workflow publishes the GitHub release *before* it uploads to
+    # PyPI (see release.yml), so triggering on `release: published` would race
+    # the PyPI upload and could pass by silently installing the prior version.
+    # workflow_run fires only after the whole Release workflow - including the
+    # PyPI publish step - has finished.
+    workflows: ['Release']
+    types: [completed]
+  workflow_dispatch:
+
+jobs:
+  verify-install:
+    if: github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success'
+    name: pip install semantica (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ['3.9', '3.10', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Pin expected version for release-triggered runs
+        id: expected-version
+        if: github.event_name == 'workflow_run'
+        shell: bash
+        env:
+          EXPECTED_TAG: ${{ github.event.workflow_run.head_branch }}
+        run: |
+          expected="${EXPECTED_TAG#v}"
+          if [ -z "$expected" ]; then
+            echo "::error::Could not determine a release tag from the triggering workflow run (head_branch was empty)."
+            exit 1
+          fi
+          echo "constraint===$expected" >> "$GITHUB_OUTPUT"
+
+      - id: setup-semantica
+        uses: ./.github/actions/setup-semantica
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+          version: ${{ steps.expected-version.outputs.constraint }}
+
+      - name: Smoke test import
+        shell: bash
+        run: |
+          python -c "
+          import semantica
+          print('semantica', semantica.__version__, 'installed and importable')
+          "

.github/workflows/release.yml

@@ -16,7 +16,7 @@ jobs:
       cancel-in-progress: false
     permissions:
       contents: write      # for the GitHub Release
-      id-token: write      # for PyPI Trusted Publishing (OIDC) and attestation signing
+      id-token: write      # for PyPI Trusted Publishing (OIDC), attestation signing, and Sigstore
       attestations: write  # for SLSA build provenance
     # If you add another job to this workflow, give it its own explicit
     # `permissions:` block rather than relying on the workflow-level default
@@ -39,11 +39,11 @@ jobs:
       # Install the pinned dependency set (with hashes) so the sdist/wheel
       # build runs against the same versions CI tests against.
       - name: Install pinned build dependencies
-        run: pip install -r requirements-ci.txt
-      - run: pip install build
-      # wheel is build-time only (not in requirements-ci.txt) — install the
-      # same pinned version [build-system] declares so --no-isolation works.
-      - run: pip install wheel==0.48.0
+        run: pip install -r requirements-ci.txt --require-hashes
+      # build is a dev-time dependency; wheel is build-time only (neither is
+      # in requirements-ci.txt) — install the same pinned versions
+      # [build-system] declares so --no-isolation works below.
+      - run: pip install -r .github/requirements/build-tools.txt --require-hashes
       - name: Build package (no isolation — pinned deps)
         run: python -m build --no-isolation
       - name: Verify Explorer frontend is packaged
@@ -63,11 +63,29 @@ jobs:
 
           print("Explorer frontend is packaged")
           PY
+      - name: Verify PyPI long-description will render
+        run: |
+          pip install -r .github/requirements/twine.txt --require-hashes
+          twine check dist/*
       - name: Attest build provenance
         uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4
         with:
           subject-path: 'dist/*'
-      - uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3
+      # attest-build-provenance publishes to the GH attestations API only, which
+      # OpenSSF Scorecard's Signed-Releases check does not inspect - it looks for
+      # signature files attached as release assets. Sign here too so
+      # `dist/*.sigstore.json` bundles ship alongside the wheel/sdist on the
+      # GitHub Release itself.
+      - name: Sign artifacts with Sigstore
+        uses: sigstore/gh-action-sigstore-python@790bc6befb9d733738f18d8f895854b453640ec9 # v3.5.0
         with:
-          files: dist/*
+          inputs: |
+            dist/*.whl
+            dist/*.tar.gz
+      - uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
+        with:
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+            dist/*.sigstore.json
       - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

.github/workflows/scorecard.yml

@@ -0,0 +1,45 @@
+name: Scorecard supply-chain security
+
+permissions: read-all
+
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: '30 1 * * 6'  # weekly
+  push:
+    branches: [main]
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write  # to upload SARIF results
+      id-token: write         # to publish results and get a badge
+      contents: read
+      actions: read           # to detect GitHub Actions workflows
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Run analysis
+        uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      - name: Upload to code-scanning
+        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
+        with:
+          sarif_file: results.sarif

.github/workflows/security-scan.yml

@@ -44,15 +44,15 @@ jobs:
         
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip
+          pip install -r .github/requirements/bootstrap.txt --require-hashes
           # Install the pinned dependency set FIRST so Safety scans Semantica's
           # exact CI/release dependency tree (requirements-ci.txt is generated
           # from pyproject.toml extras, so this covers the project's real deps).
-          pip install -r requirements-ci.txt
+          pip install -r requirements-ci.txt --require-hashes
           # Tooling AFTER the pinned set: installing safety/bandit/semgrep/jq
           # first lets the pinned requirements overwrite their transitive deps
           # (e.g. rich), which breaks the safety CLI at runtime.
-          pip install safety bandit semgrep jq
+          pip install -r .github/requirements/security-scan-tools.txt --require-hashes
 
       - name: Run Safety Check (Package Vulnerabilities)
         run: |

.github/workflows/security.yml

@@ -25,18 +25,18 @@ jobs:
       # Upgrade first: actions/setup-python's baked-in setuptools has been
       # behind known-vulnerable floors before (e.g. PYSEC-2026-3447 /
       # setuptools 75.1.0), so don't trust the preinstalled one.
-      - run: python -m pip install --upgrade pip setuptools
+      - run: pip install -r .github/requirements/bootstrap.txt --require-hashes
       # Audit the pinned dependency set (requirements-ci.txt is compiled from
       # pyproject.toml with --extra all — the same coverage as the [all]
       # extra, minus the Linux-only gpu set — so this keeps scan parity with
       # CI/release builds without a time-dependent resolution). This is the
       # fix for PYSEC-2024-38 (#869): the bare-env job never had fastapi or
       # python-multipart installed to look at.
-      - run: pip install -r requirements-ci.txt
+      - run: pip install -r requirements-ci.txt --require-hashes
       # PR runs gate on findings, since they're scoped to actual
       # pyproject.toml changes under review. The schedule/workflow_dispatch
       # runs stay non-blocking until a full pass over pre-existing findings
       # across the whole [all] tree has been done.
-      - run: pip install pip-audit
+      - run: pip install -r .github/requirements/pip-audit.txt --require-hashes
       - run: pip-audit -r requirements-ci.txt
         continue-on-error: ${{ github.event_name != 'pull_request' }}

CHANGELOG.md

@@ -9,6 +9,111 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.7] - 2026-08-28
+
+### Added
+
+- **First-class LangChain integration** (closes #963; recreates #969)
+  - New `pip install semantica[langchain]` extra (`langchain-core>=0.3.0`), included in the `all` bundle
+  - `integrations/langchain/SemanticaRetriever` — LangChain `BaseRetriever` that seeds from `HybridSearch` then walks graph edges (`hops=2` default) for GraphRAG-style retrieval; falls back to `ContextGraph.query` when hybrid search is unavailable
+  - `integrations/langchain/SemanticaVectorStore` — LangChain `VectorStore` adapter over `HybridSearch` (`add_texts`, `similarity_search`, `similarity_search_with_score`, `from_texts`)
+  - `integrations/langchain/SemanticaKGTool` / `SemanticaDecisionTool` — `BaseTool` subclasses with Pydantic `args_schema` (`semantica_query_graph`, `semantica_query_decisions`); `build()` returns the tool, or `None` when langchain-core is absent
+  - Retriever and VectorStore read HybridSearch nested `metadata` (`content`, `node_id`, `node_type`) rather than top-level fields that HybridSearch does not set
+  - All adapters remain importable without langchain-core (`LANGCHAIN_AVAILABLE` flag)
+  - Docs: `docs/integrations/langchain.md`, README native-integration matrix, and `docs.json` nav entry
+
+- **SAP OData ingestor** (#1234, closes #1228) by @pkupt
+  - New `SAPODataEntity` / `SAPODataConnector` / `SAPIngestor` (`semantica.ingest`, lazy exports), following the three-layer connector pattern already used for Snowflake/Databricks, to pull master/transactional data (Business Partners, Sales Orders) from SAP OData v2/v4 services into the Context Graph
+  - Dual auth (OAuth2 client-credentials for BTP/S4HANA Cloud, Basic for on-prem NetWeaver); every outbound request, including the token exchange, routes through `request_with_ssrf_guard`
+  - `$metadata` (CSDL XML) is parsed with a hand-rolled `xml.etree` reader rather than pulling in `pyodata`; pagination follows OData v2 `__next`/`__deferred` and v4 `@odata.nextLink`
+  - New `pip install semantica[ingest-sap]` extra (`requests>=2.28.0`)
+  - **Known phase-1 limits** (documented in docstrings): the OAuth2 token is cached but never refreshed, and pagination has no `max_pages` fuse (`top` bounds it when supplied)
+  - New `tests/ingest/test_sap_ingestor.py`: 22 tests (auth, EDMX parsing, v2/v4 pagination, SSRF routing, error paths, service-root normalization)
+
+- **`ContextGraph` gains deterministic, human-editable Markdown round-trip persistence** (#852) by @SaurabhScripts
+  - `save_to_markdown()`/`load_from_markdown()` write one file per node plus a graph manifest, so a graph can be reviewed and hand-edited outside the application without giving up the existing JSON API or its default behavior
+  - An existing destination is validated as a complete, canonical managed export before atomic replacement, so the loader can't silently clobber an unrelated or manually-extended directory
+  - Import/export paths and their ancestors reject symlinks, Windows junctions, and other reparse points, with pre-open and post-open validation — the same hardening applied to `AgentMemory`'s existing Markdown import in the companion fix below
+  - Dangling edge endpoints import as JSON-compatible entity stubs rather than being rejected outright (matching what the JSON loader already accepts); node/edge indexes, adjacency, and analytics/retraction/tombstone state are rebuilt after a Markdown load, and granular node/edge events are still emitted so temporal audit history stays useful
+  - New `tests/context/test_context_graph_markdown.py`: 29 passed, 1 skipped (the skipped case creates a real Windows junction and runs on Windows CI); full `tests/context/` suite: 614 passed, 1 skipped
+
+- **Explorer graph inspector gains a read-only Markdown content viewer** (#1078, closes #900) by @sakshi04-ui — Preview (rendered GFM) and Source (exact, whitespace-preserving) tabs for node content, with a copy-to-clipboard action. A URL allowlist restricts links to `http:`/`https:`/`mailto:`/in-document anchors, raw HTML execution is disabled, and external links carry `rel="noopener noreferrer"`. A first, focused step toward human-editable memory (#765); no write path yet. New `explorer/tests/markdownContentViewer.test.ts`: 8 tests
+  - **Follow-up (perf)** (#1195, addresses #1118) by @pravit-amp: `remarkPlugins` and the ~20-entry renderer `components` map were inline literals, so every unrelated re-render (e.g. clicking Copy) re-ran the full remark parse and remounted the whole subtree — up to 1.1s of main-thread block on a 2000-row GFM table. Both are now hoisted to module scope and the rendered element is memoized on content, cutting re-render cost from as much as 1121ms to ~0.1ms across all measured fixtures with no change to rendered output. A separate, upstream `remark-gfm` table-parse cost (~O(n^1.9), not fixed here) is left open on the issue as a product decision
+  - **Follow-up (cleanup)** (#1194, closes #1119) by @pravit-amp: the pure `isSafeUrl` URL-safety helper is extracted out of `MarkdownContentViewer.tsx` into its own `markdownUrlSafety.ts` module (behavior-preserving — moved verbatim), so the component module exports only components and stops tripping `react-refresh/only-export-components`
+
+- **`reasoning` gains a structured Action layer — rule-driven side effects with optional provenance** (#1096, closes #1095) by @cxzg007 — `AssertAction`/`RetractAction`/`CallAction`/`EmitEventAction` let a matched rule write facts back to a `KnowledgeGraph`, retract facts, call a structured handler (replacing the previously-unused `Rule.handler`), or emit to a sink registered via `Reasoner.on_event`, turning the reasoner from a pure inference engine into a production-rule system. With `provenance=True`, fired actions are recorded to `Reasoner.action_log`. Fully additive — rules without `actions` are unaffected, and the legacy `handler` field still fires (now wrapped internally as a `CallAction`). Also fixes a latent dangling import in `reasoning_provenance.py` (`ReasoningEngine`/`infer` → `Reasoner`/`infer_facts`). New `tests/reasoning/test_rule_actions.py`: 9 tests; full `tests/reasoning/` suite: 54 passed
+
+- **`run_shacl_validation` is now a public, documented entry point** (#1189, closes #1186) by @mikemikimike — the SHACL guide had documented the private `_run_pyshacl` helper as the canonical API; it's now exposed through `semantica.ontology`, with `_run_pyshacl` kept as a compatibility alias over the same implementation. `tests/ontology/test_ontology_advanced.py`: 33 passed (also fixes a flaky comparison against pySHACL's non-deterministic blank-node shape identifiers by comparing stable report fields instead)
+
+- **`docs/storage-backends.md`: adapter inventory and RDF/LPG feature matrix** (#899, addresses #888) by @yulinlina — which graph storage backends are built-in vs. bring-your-own, and where provenance/context support is partial
+- **`docs/guides/shacl-validation.md`: documented that `rdfs:range` + RDFS entailment makes `sh:class` unfalsifiable** (#1182, fixes #1130) by @ALDRIN121 — with entailment on, pyshacl infers the declared range class onto every object, so a `sh:class` constraint can never fail and reports `conforms: True` on non-conforming data; added to Common Pitfalls with the `inference="none"` vs `inference="rdfs"` contrast and guidance to re-run `sh:class` shape sets with entailment off before trusting a pass
+- **Cookbook: four new module notebooks** — `22_Provenance_Tracking.ipynb` (#989, lineage walks, revision history, invalidation, checksums), `23_Reasoning.ipynb` (#990, `Reasoner`/`DatalogReasoner`/`ExplanationGenerator`), `24_Change_Management.ipynb` (#991, versioned snapshots, named tags, checksum tamper-detection), and `25_Seed_Data.ipynb` (#992, bootstrapping a foundation graph from a trusted CSV source) — all by @LeonSGP43, filling gaps where the corresponding module shipped a usage doc but no runnable tutorial; every cell verified against current module source. `docs/cookbook.md` index entries for all four added in #1225
+- **README "Cite Us" section and `docs/citation.md` cross-link** (#1210) by @KaifAhmad1 — BibTeX/APA/MLA/Chicago/IEEE citation forms; also corrects the copyright holder in `LICENSE`/`docs/project-license.md` from the stale "Hawksight AI" to "Semantica" and replaces the retired `Hawksight-AI` GitHub org slug with `semantica-agi` across ~40 files (READMEs, issue templates, plugin manifests, cookbook notebooks, docs)
+
+### Changed
+
+- **A registered custom method can now refuse, instead of being silently overridden by the default implementation** (#1127, closes #1108) by @fabio-rovai — every module supporting custom methods wrapped the registered callable in a `try`/`except` that logged a warning and ran the built-in default on *any* exception, including one a validator or policy gate raised on purpose to say "do not produce this output." That made every registered gate advisory rather than authoritative. `semantica/utils/custom_methods.py` now centralizes the policy: an exception from a registered method propagates to the caller by default; `fallback_on_custom_error=True` restores the previous warn-and-continue behavior per call. Applied mechanically across all 58 call sites in `export/`, `ingest/`, `normalize/`, `parse/`, `embeddings/`, and `kg/` methods modules. New `tests/utils/test_custom_method_can_refuse.py`: 13 tests, including the reported gate-deletes-and-raises scenario and a guard that no call site still swallows
+- **Removed 13 confirmed-dead symbols across 9 files** (#1176, closes #1174) by @Vinv-AI — private helpers and Explorer app-layer code with zero callers in code, tests, or docs, none part of the public API or a FastAPI `response_model`; 289 deletions, no behavior change
+- **Consolidated the two duplicate Turtle/N-Triples literal escapers in `rdf_exporter.py`** (#1221, closes #1218) by @pkupt — `_escape_turtle_literal` (added in #1148) escaped the same five characters in the same order as the older module-level `_escape_literal`; the redundant one is dropped and all four call sites route through the original. Behavior no-op, verified against the full export suite (301 passed, 1 skipped)
+- **Removed the unreachable `_extract_with_spacy()` method and the unused `self.nlp` attribute from `NERExtractor`** (#1220, fixes #1058) by @yunaremaia — the ML dispatch path has always gone through `methods.py`'s process-level model cache instead; `__init__` still validates the spaCy runtime up front but no longer eagerly loads a model nothing on the instance reads
+- **Cleaned up an unused `sys` import and import ordering in `semantica/worker.py`** (#1061) by @aoright
+- **Test-only contributions**: isolated `sys.modules` mock leakage between `tests/visualization/` files so the suite passes in any collection order (#897, closes #859, by @luantaraschi); added coverage for 4 previously-untested `ConflictResolver` strategies and 3 `ConflictDetector` conflict types (#902, fixes #865, by @Devansh070); added a regression test tracking relationship provenance through `ProvenanceManager` (#1071, closes #1055, by @dex0shubham); added `max_tokens`-propagation regression coverage for LLM extraction methods, later folded into the cache-key fix below (#925, by @saiganesh47)
+
+### Fixed
+
+- **`SPARQLReasoner.execute_query()` claimed to run a query but always returned an empty result** (#1087, fixes #1083) by @ALDRIN121 — both the store-configured and unconfigured branches returned an empty `SPARQLQueryResult` with no real execution behind it, so a caller trusting "no matches" (e.g. a compliance check) could draw a false-negative conclusion from a method that never actually queried anything. Until a real triplet-store execution path lands, it now raises `NotImplementedError` explaining why, and the dead cache/inference scaffolding after the unreachable execution point is removed. 3 new regression tests
+- **`DuplicateDetector` merged entities that share no identifier, type, or name** (#1149, fixes #1137) by @pkupt — `_create_duplicate_candidate()` only ever boosted confidence for matching types and never penalized a mismatch, so two sparse, differently-typed entities (e.g. a `Person` and an `Organization`) could land above the merge threshold and collapse into one node, silently dropping the second. Two non-empty, differing types are now never a duplicate candidate. `tests/deduplication/`: 92 passed
+- **`TemporalGraphQuery.analyze_evolution()`'s `stability` metric was a hardcoded placeholder** (#1143, closes #1142) by @cxzg007 — every bounded relationship contributed a constant `1`, so `stability` was always `1.0` or `0` regardless of how long relationships actually stayed valid. Now computes the mean valid-time duration in seconds across relationships with both `valid_from`/`valid_until` set; unbounded/half-open intervals are skipped and negative intervals clamp to zero. 3 new tests in `tests/kg/test_kg.py`
+- **CodeQL false-positive on a JSON-LD test's URL check** (#1183) by @KaifAhmad1 — `"https://schema.org/" in flattened` pattern-matched CodeQL's substring-sanitization heuristic even though `flattened` is always a `list` (exact membership, no sanitization or SSRF path involved); rewritten as an explicit `any(entry == ... for entry in flattened)` with identical behavior
+- **HuggingFace NER extraction crashed on `huggingface_model` being forwarded as an unexpected pipeline loader kwarg** (#1188, fixes #1063) by @shahzaib-ahmadcs — while preserving genuinely supported pipeline kwargs like `aggregation_strategy`. 5 tests pass
+- **JSON-LD document/graph `@id` was minted from the wall clock, so re-exporting an unchanged graph produced a new subject every time** (#1181, closes #1147) by @reddynitish — merging repeated exports duplicated graph identity instead of recognizing them as the same graph. The `@id` is now content-derived, with optional `graph_uri`/`document_uri` overrides for callers with a stable graph name; `semantica:exportedAt` still records export time separately. Applies to both JSON-LD export paths
+- **`ContextGraph.get_causal_chain()` only matched the canonical uppercase causal-edge spellings, silently missing edges recorded in `CausalChainAnalyzer`'s present-tense vocabulary** (#1187, fixes #1184) by @ALDRIN121 — `causes`/`influences`/`precedes` differ from `CAUSED`/`INFLUENCED`/`PRECEDENT_FOR` in word form, not just case, so an edge recorded with the analyzer's spelling produced an empty audit chain — silent, and in the dangerous direction for a compliance trace. `add_causal_relationship()` now normalizes through an alias map before storing the canonical form; traversal accepts the union vocabulary. 2 new regression tests, full `tests/context/` suite: 587 passed
+- **`semantica embed generate` corrupted its own output and could recurse into a stack overflow** (#996/#1004/#1005, closes #994) by @varunsahni18, @yzxcj797 — three compounding defects in one pipeline. (1) `generate_embeddings`/`embed_text`/`calculate_similarity`/`pool_embeddings` all registered themselves as their own custom-method-registry default, so an unqualified call (exactly what the CLI does) re-entered the same wrapper until Python's recursion limit; each of the four dispatch sites now guards on registry identity before recursing (#996, #1005). A second self-recursion in `EmbeddingGeneratorWithProvenance.__getattr__` (re-entering itself when `_generator` is unset, e.g. during a `deepcopy` probe) now raises a normal `AttributeError` for private names instead (#1005). (2) `--output embeddings.parquet` wrote `json.dumps(result, default=str)` regardless of extension, turning a numpy array into its plain-text `repr()` — a file `embed index` then failed to open as Parquet; the writer now detects `.parquet`/`.json`/`.jsonl` and produces real Parquet/JSON, rejecting any other extension with a clear message (#996, #1004). (3) `pyarrow` was only in optional extras despite being required by the documented quick-start flow; promoted to a core dependency (#996)
+- **`AgentMemory`'s existing Markdown import accepted symbolic links, NTFS junctions, and other Windows reparse points** (#851) by @SaurabhScripts — a direct linked import path is now rejected with an actionable error, and a linked entry found inside an otherwise-valid directory is skipped rather than aborting the whole import; hardened with pre-open/post-open checks, `O_NOFOLLOW` where available, and `fstat`-based regular-file validation. `tests/context/`: 595 passed, 1 skipped (Windows-junction test, runs on Windows CI)
+- **A caught vector-similarity scoring exception left stale partial state behind, risking a misleading match on the next call** (#885, fixes #875) by @ArmanGrewal007 — the exception is now logged at debug level and `vector_score`/`vector_idx` reset to neutral values before the remaining matching stages continue
+- **`RDFExporter` could write invalid or unintended relative IRIs for `GraphBuilder`-default entity/relationship identifiers** (#1112, closes #1099) by @mikemikimike — normalization is now applied at the RDF export boundary across Turtle (including temporal Turtle), RDF/XML, and N-Triples: bare/relative identifiers are minted under the Semantica namespace with safe percent-encoding, absolute IRIs pass through unchanged, and configured/input-context prefixes expand through the effective namespace mapping. 38 focused regression tests; 175 export tests plus 46 subtests pass
+- **`RDF4JStore`'s `repository_id` constructor argument had no effect** (#1192, closes #1191) by @Freakz2z — the explicit id is now honored when selecting the repository; stale documentation caveats claiming otherwise are removed. 65 tests pass across the affected triplet-store suites
+- **Non-interactive stdout (piped/redirected output, CI logs) was flooded with progress-bar escape sequences** (#1193, fixes #1185) by @ALDRIN121 — a plain `python demo.py > out.txt` captured 173 bytes of progress noise around 10 bytes of real output. `ProgressTracker` now attaches its console display only for an interactive terminal, Jupyter, or the new `SEMANTICA_FORCE_PROGRESS` opt-in (following the `NO_COLOR`/`FORCE_COLOR` convention); file-based progress logging is untouched. Both switches are now documented in the README and `docs/reference/utils.md`. 11 tests pass (6 new)
+- **Entity `metadata` was dropped by every RDF serializer except the JSON-LD path**, so an entity kept its confidence but lost its source document, page, extractor, and reviewer on Turtle/N-Triples/RDF/XML/`RDFExporter`'s own JSON-LD (#1165, closes #1154) by @fabio-rovai — Semantica's own metadata keys (`num_entities`, `snapshot_time`, Neo4j loader fields, etc.) are now mapped to declared vocabulary terms and carried through on every path; a caller-supplied key with no mapped term is skipped with an explicit warning (rather than silently vanishing) naming the override needed, pending the caller-key namespace decision tracked in #1146. 21 new tests in `tests/export/test_metadata_passthrough.py`; `tests/export`+`tests/ontology`: 274 pass
+- **`extract_relations_llm` silently dropped caller-supplied generation parameters** (`max_tokens`, `top_p`, `seed`, etc.), and the extraction cache didn't distinguish calls made with different generation settings (#1213, with test coverage from #925) by @Sameer6305 — a small hardcoded allowlist forwarded only `temperature`/`verbose` to `generate_typed`, discarding the rest; fixed by forwarding all caller kwargs. Once forwarded, those parameters also needed to enter the cache key, since two calls differing only in `max_tokens` previously shared one cache entry and the second could silently reuse a result generated under the first's settings — now applied consistently across entity, relation, and triplet LLM extraction. New regression tests for cache bypass/reuse under differing `max_tokens`/`temperature`
+- **`OxigraphStore` silently ignored the `storage_path` constructor argument and never flushed writes before a reopen**, both causing silent on-disk data loss (#970) by @logan-jl-cc — `__init__`'s parameter is named `path`, so the project-conventional `storage_path` landed in `**config` and was ignored, degrading a supposedly-persistent store to in-memory with no error; `storage_path` is now accepted as an alias. Separately, pyoxigraph's background flush can lag behind a write, so a reopen immediately after `add_triplets` could observe fewer triples than were written; writes to an on-disk store now call `flush()` explicitly. 2 new regression tests, full suite: 9 passed
+- **MCP server's `export_graph` tool was broken on every output format** (#1151) by @Arasz — the `json` branch called `JSONExporter().export()` without the `file_path` it requires, and every RDF branch passed a `ContextGraph` object where the exporters expect the canonical kg dict, both surfacing as a raw exception string. A third bug compounded both: the RDF export path's progress bar wrote to stdout, which over stdio MCP *is* the JSON-RPC framing, corrupting the protocol and hanging the client (a 300s timeout on an empty graph). Fixed by converting through `ContextGraph.to_kg_dict()`, serializing the JSON branch to match the RDF branches' string contract, and forcing `SEMANTICA_DISABLE_PROGRESS=1` for the server process. 5 new tests, verified failing against 0.6.6 beforehand
+- **`OntologyIngestor` dropped every class and property from a JSON-LD document using a named graph** (#1156, fixes #1129) by @13g4d0 — a top-level `@id` beside `@graph` names the graph, and `rdflib.Graph.parse()` silently loads only the default graph, discarding the rest; `POST /api/ontology/load` returned `status: "success"` with `class_count: 0`. Now parses into a `Dataset` and flattens all quads into the working graph (the same `Graph`→`Dataset` migration #757 made for `JenaStore`, extended to the ingest path). On the PR's real-world reproduction: 25 triples/1 subject before, 719 triples/45 classes/40 object properties after. 4 new tests including a default-graph canary so the fix can't trade one blind spot for another
+- **Turtle and N-Triples RDF export interpolated entity `text` into string literals with no escaping**, so a `"`, backslash, newline, CR, or tab in the source text emitted invalid RDF other parsers rejected (#1148, closes #1098) by @pkupt — a shared `_escape_turtle_literal()` (later consolidated in #1221) now escapes per the RDF 1.1 Turtle grammar and is reused for the N-Triples path, which previously escaped only quotes and newlines. `tests/export/`: 161 passed, 1 skipped
+- **`PipelineSerializer` round trips dropped step dependencies and delta-processing metadata, and could rehydrate a legacy stringified handler as a non-callable string** (#1217, fixes #1216) by @cxzg007 — step dependencies, delta mode, and base/target version IDs are now restored from the serialized schema; runtime handler callables are treated as process-local state and excluded from serialized business configuration rather than (mis)serialized. 52 tests pass
+- **`PipelineBuilder` never actually dispatched to a handler registered by `step_type`**, and a serialize/deserialize round trip could leak `handler`/`dependencies` into a step's business config (#1215, fixes #1214) by @cxzg007 — a registered handler is now resolved by `step_type` when no explicit `handler=` is supplied (explicit handlers still take precedence), and the two builder-control fields are kept out of `PipelineStep.config` so a strict handler signature can't receive them as unexpected kwargs. `tests/core`+`tests/pipeline`: 50 passed
+- **`PipelineBuilder.set_parallelism()` was accepted and stored but never read — pipeline steps always ran strictly sequentially**, and the setting didn't survive a serialize/deserialize round trip (#1226, fixes #1223) by @cxzg007 — wired through builder → serializer → execution engine, plus a new opt-in `PipelineStep.parallel_safe` flag. A dependency layer now runs in parallel only when every step in it is marked `parallel_safe`, the layer has more than one step, the input is dict-typed, and no step is in delta mode; otherwise it falls back to sequential execution. Each parallel step's input is deep-copied for isolation, execution is bounded by `ThreadPoolExecutor(max_workers=min(configured parallelism, max_workers))`, a failure cancels pending futures in the layer, and layer results merge back in declaration order (a same-key conflict raises `ProcessingError`). 22 new tests in `tests/pipeline/test_pipeline_parallel.py`
+- **`Config.get()` silently dropped boolean environment-variable overrides** (#1038, fixes #1035) by @Kyou12138 — the type dispatch checked `isinstance(default, int)` before `isinstance(default, bool)`, and since `bool` subclasses `int` in Python, the bool branch was unreachable: `CONFLICT_ZZTESTFLAG=true` with a `False` default returned `False`, and `=1` returned the int `1` rather than `True`. Bool is now checked first (with whitespace stripped before parsing truthy/falsy spellings), fixed across all ten affected config modules (`conflicts`, `deduplication`, `split`, `embeddings`, `export`, `ingest`, `kg`, `parse`, `ontology`, `normalize`). 12 new tests plus 6 existing conflicts tests and 131 related module tests pass
+- **Scanned (image-only) PDFs parsed with no error and no warning, returning empty text with a "completed" status** (#1021, closes #1020) by @shanyu910 — `PDFParser._parse_page` swallowed a missing text layer via `page.extract_text() or ""`, so the failure only surfaced far downstream as zero extracted entities. A warning now fires when every parsed page yields no text with `extract_text` enabled, pointing at `parse_pdf(..., method="docling", enable_ocr=True)`. Also fixes a separate `import semantica.parse` failure on a fresh interpreter (`email_parser.py` used `email.message.Message` without importing `email.message`) that was blocking the parse test suite from even collecting. 25 tests pass in `tests/parse/`
+- **`GET /api/decisions` returned HTTP 422 for any graph containing real decisions**, breaking the Explorer Decisions workspace entirely (#937) by @logan-jl-cc — `record_decision()` stores the timestamp as a POSIX float, but `DecisionResponse.timestamp` is typed `Optional[str]` and Pydantic's strict mode rejected the coercion. Fixed by coercing to `str` (preserving `None`) at the response-adapter boundary
+- **Decision persistence/query bugs, CJK text handling, and three missing MCP graph tools** (#967) by @toratto — `mcp_server`'s `_get_graph` called a non-existent `graph.load` instead of `load_from_file`, so `SEMANTICA_KG_PATH` was silently ignored and the server always started with an empty graph; `query_decisions` read `category` from the wrong field, always returning nothing for a category filter; `find_precedents`/`query_decisions(query=)`'s similarity threshold was too high for short CJK queries, which also failed outright because `_calculate_decision_content_similarity`'s whitespace-Jaccard fallback is always zero for languages with no whitespace tokenization (now falls back further to a character-bigram overlap coefficient); `load_from_file` didn't rebuild the in-memory decision/entity/temporal indexes after loading, breaking `find_precedents_by_scenario` and decision counts post-reload; `extract_entities`/`extract_relations` returned the spaCy type label as `text` and dropped the actual entity text, and had no way to select a non-English NER model. Also adds three new MCP tools (`query_graph`, `update_node`, `delete_node`, the latter two persisting back to `SEMANTICA_KG_PATH`)
+- **`sqlalchemy.text` was used but never imported in two `DBIngestor`/`DataExporter` methods**, raising `NameError` on every call before any query reached the database (#1017, closes #1015) by @pravit-amp — `connect()`/`test_connection()` imported `text` function-locally, so the binding never reached `export_table_data()` or `execute_query()`, which called it anyway; both raised immediately, re-wrapped by an `except Exception` into a `ProcessingError` that read like a database fault rather than a missing import. `docs/guides/ontology.md` documents `DBIngestor().execute_query()` as a supported entry point, so documented usage walked straight into it. 5 new tests against a temporary SQLite database, also repairing a previously-failing `tests/ingest/test_notebook_02.py` case
+- **Ontology generation resolved relationship endpoint types incorrectly, producing wrong object-property domains/ranges** (#1170, closes #1168) by @T1mn — endpoint types are now resolved from the canonical `source_id`/`target_id` fields and supported aliases instead of defaulting to the first entity when a field was missing, preventing e.g. a `Person -> Organization` relationship from generating a `Person -> Person` property. 80 tests pass, 1 skipped
+- **Ontology property generation dropped data properties when a raw entity type was normalized into a class name** (#1171, closes #1169) by @T1mn — e.g. `software engineer` → `SoftwareEngineer` lost its `email` property; attributes are now grouped by matching raw, normalized, and recorded class names, so the normalized class stays each property's domain. 79 tests pass, 1 skipped
+- **`flatten_dict()` silently dropped data when a top-level key already containing the separator collided with a key produced by flattening a nested dict** (#1012, fixes #1010) by @yzxcj797 — `{"a.b": 1, "a": {"b": 2}}` flattened to `{"a.b": 2}` with no error, the `1` simply gone; collisions are now detected (unique-key count vs. item count) and raise `ValueError` naming the colliding key before data is lost. 6 new tests
+- **Creating relationships after `GraphStore.add_edges`/`build_from_entities_and_relationships` silently produced zero edges against ID-minting backends** (#1173, fixes #1136) by @yzxcj797 — an id-space mismatch across three layers: `add_edges` reads application-level string ids and passes them to `create_relationship`, which is a pure passthrough into `Neo4jStore.create_relationship`'s `MATCH ... WHERE id(a) = $start_id` — a Neo4j-internal integer id. Every node was created and every relationship silently failed with one easily-missed warning per edge. `GraphStore` now keeps an application-id→internal-id map, populated by `add_nodes`/`create_node` from the backend's own creation results and consulted by `create_relationship`; unknown ids and identity-mapped backends are unaffected. `tests/graph_store/`: 100 passed
+- **RDF export left `semantica:text`/`rdfs:label` empty for entities that only carry a `name` field**, across all four RDF formats (#1113, fixes #1097) by @cxzg007 — `RDFSerializer.convert_kg_to_rdf()` already implemented the `name`→`label`/`text` normalization, but `export_to_rdf()` never called it. Now called once at the export boundary (idempotent, non-destructive, falls back to a label derived from the id suffix). 7 new tests, `tests/export/test_rdf_exporter.py`: 17 passed
+- **Docker Explorer image failed to build on Python 3.14** — `gensim` has no prebuilt wheel for it and the slim base has no `gcc` to build from source (#1172, closes #1025) by @DwitiThaker — runtime pinned to `python:3.13-slim`, where `gensim` installs from a prebuilt wheel
+- **Unit normalization rejected common aliases before conversion** — `kg`, `g`, and other abbreviated/plural unit spellings failed category validation and the conversion-factor lookup ahead of it (#939) by @Mr-Neutr0n — aliases now normalize first; canonical aliases added for feet, yards, miles, and gallons. 7 tests pass
+- **An oversized, caller-controlled mapping key could blow up a `ValidationError` message to megabyte scale**, and equally inflate application logs on repeated malformed input (#1088, fixes #1001) by @ALDRIN121 — follow-up to the graph-payload validation added in #958. The displayed key is now truncated at 64 characters with an ellipsis; the underlying input and validation decisions are unchanged. 4 new tests
+- **`SeedDataManager.load_from_api()` mislabeled genuine connection failures as a missing `requests` dependency** (#972, closes #949) by @pravit-amp — `requests.exceptions.RequestException` (connection errors, timeouts, `raise_for_status()` failures) subclasses `OSError`, so an `except (ImportError, OSError)` block written to guard a lazy import that no longer existed (`requests` is a core dependency) caught real failures too and told users to reinstall an already-installed library while dropping the original exception chain. The block is removed; genuine failures now surface through the existing `Failed to load from API: {e}` path with `from e` intact. 5 new regression tests
+- **`SHACLGenerator` produced shapes that matched nothing, and pySHACL reported `conforms: True` on data that plainly violated them** (#1124, closes #1104, closes #1105) by @fabio-rovai — `base_uri` was used both as where shape resources live and to expand every `sh:targetClass`/`sh:path`, so with the default shapes namespace, generated shapes targeted classes no data graph in the package actually uses; a shape with zero matching focus nodes is vacuously satisfied, so validation silently passed regardless of real violations. The target namespace now resolves independently (explicit argument → ontology's declared namespace → an existing absolute class/property IRI → ontology `uri` → the vocabulary namespace), never the shapes namespace. Separately, `_attach_property_shapes` attached a domain-less property's constraint to *every* shape ("no domain declared, attach to all"), asserting a constraint the ontology never stated; a domain-less property is now left unattached by default, with `attach_domainless_properties=True` to restore the old behavior. 17 new tests validate real data through pySHACL rather than reading shape text; `tests/ontology`+`tests/export`: 239 passed
+- **OWL export dropped every generated property and collapsed distinct classes onto one node** (#1123, closes #1103) by @fabio-rovai — `OWLExporter` reads `object_properties`/`data_properties`, but `OntologyGenerator` emits one combined `properties` list, so every property was silently discarded; separately, a class built without a namespace manager gets `"uri": None`, which a `"uri" not in cls"` guard never catches (the key is present), so the exporter wrote a relative `<>` IRI for it — resolved by rdflib against the current working directory, meaning two classes could collapse onto one subject and that subject's identity changed with the export's working directory. Both dict shapes are now merged and classified correctly, and a class/property IRI resolves through `uri`→`iri`→`id`→a name joined onto the ontology base, skipping (with a warning) a term with none of those instead of minting `<>`. 10 new regression tests parse the real output with rdflib and Oxigraph; `tests/export`+`tests/ontology`: 231 passed
+- **Confidence scores serialized as four different, mutually-disagreeing RDF terms depending on export format, and one non-numeric confidence value could break an entire Turtle export** (#1125, closes #1100, closes #1102) by @fabio-rovai — Turtle wrote a bare `xsd:decimal`, N-Triples an explicit `xsd:float`, RDF/XML an untyped plain literal, and JSON-LD's native number expanded to `xsd:double`; loading a Turtle and an N-Triples export of the same graph into one store gave the same entity two different confidence values. Separately, an unparseable confidence (e.g. the string `"high"`) was interpolated into Turtle with no validation, producing a syntax error that dropped every entity from the export. All four paths now write one canonical `xsd:decimal` lexical form (matching the pre-existing Turtle behavior and the only exact representation of the four); an unusable value is omitted with a warning instead of corrupting the document. The vocabulary's `sem:confidence` now declares `xsd:decimal` (previously left undeclared to avoid contradicting the disagreeing exporters). 20 new tests compare parsed graphs across all four formats; `tests/export`+`tests/ontology`: 240 passed
+- **An OWL-Time validity interval was reified onto a relationship IRI the graph never actually referenced**, making it unreachable from the edge it described (#1126, closes #1106) by @fabio-rovai — a relationship serializes as a single triple with no node of its own, so `include_temporal=True` minted a well-formed `time:Interval` with zero inbound arcs to its subject. Turtle now also emits the `sem:Relationship`/`sem:source`/`sem:target`/`sem:type` reification the JSON-LD path already produced, but only when there's temporal data to attach — default and `include_temporal=False` output are byte-for-byte unchanged. 7 new tests include a SPARQL walk from the edge to its interval, the path the dangling node made impossible; `tests/export`+`tests/ontology`: 228 passed
+- **JSON-LD exports were unreadable by Semantica's own default parser** (#1145, fixes #1144) by @fabio-rovai — every export was written as a named graph (a top-level `@id` beside `@graph`), which a plain `rdflib.Graph.parse()` silently discards in favor of the (empty) default graph; a two-entity graph parsed as 2 triples instead of 20. Compounded by `export_knowledge_graph` converting its payload to JSON-LD and then handing the *already-converted* document to `export()`, which converted it again, producing two `@context` blocks and two document nodes. Metadata now attaches beside `@graph` rather than naming it, and a payload that already declares `@context` is merged rather than re-wrapped. 9 new tests parse with both `Graph()` and `Dataset()` and assert identical counts; full-suite failure set unchanged before/after (539/539)
+- **`GraphBuilder` didn't propagate entity-resolution's merged ids into the `source_id`/`target_id` relationship aliases**, only `source`/`target` (#1115, closes #1110) by @T1mn — a relationship's alias fields could still point at a pre-merge id after resolution. Both alias pairs are now kept in sync. 9 tests pass
+- **`GraphValidator` indexed entities only by `id`, rejecting graphs that use the `entity_id` alias as invalid even when their relationships were fine** (#1116, closes #1111) by @T1mn — validation and endpoint checks now go through the shared `get_entity_id()` helper, accepting both fields consistently. 5 tests pass
+- **Broken star history chart in README** (#1057) by @OctoBored — the embedded chart used the GitHub stargazer API, now access-restricted; switched to a token-free alternative data source
+
+### Security
+
+- **Agno's `AgnoKnowledgeGraph.load_urls()` made outbound requests with no SSRF protection beyond a scheme check** (#1212) by @Sameer6305 — caller-supplied URLs went straight to `urllib.request.urlopen()`, unguarded against loopback/private addresses, cloud metadata endpoints (`169.254.169.254`), IPv6-internal addresses, hostnames resolving to private space, or redirects into any of the above. Found during a project-wide SSRF audit following #936/#959. Now routed through the shared `request_with_ssrf_guard()`; an unsafe URL is skipped rather than aborting the rest of the ingestion batch. `OpenClawKGTool` (operator-configured, intentionally allowed to target `localhost` for local deployments) gains scheme/malformed-URL validation as defense in depth, without restricting its legitimate private-network use case. 29 new Agno tests, 26 new OpenClaw tests, all passing alongside the 15 pre-existing Agno integration tests
+
+### Dependencies
+
+- Routine version bumps with no application-facing behavior change: `anthropic` 0.121.0→0.122.0 (#1045), `botocore` 1.43.69→1.43.73 (#1047), `agno` 2.8.7→2.9.0 (#1050), `google-genai` 2.17.0→2.18.1→2.19.0 (#1163, #1205), `lxml` 6.1.1→6.1.2 (#1197), `charset-normalizer` 3.5.0→3.5.1 (#1201), `pypickle` 2.0.1→2.0.2 (#1203)
+
 ## [0.6.6] - 2026-08-20
 
 ### Added
@@ -108,6 +213,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **RETE engine matched every fact against every rule — `AlphaNode._matches()` and `BetaNode._can_join()` were placeholder stubs that always returned `True`** (closes #300)
+  - `semantica/reasoning/rete_engine.py` shipped a Rete network whose per-condition alpha test and cross-condition beta join were both `return True` stubs, so `match_patterns()` fired every rule for every fact regardless of predicate, arity, or shared-variable consistency
+  - New module-level `unify_condition()` reuses the regex-based approach from `Reasoner._match_pattern()`: a condition pattern like `Person(?x)` / `Parent(?x, ?y)` is compiled against a fact's `predicate(arg, ...)` string, `?var` becomes a named capture group, and a variable seen twice within one condition (e.g. `Loves(?x, ?x)`) becomes a backreference, so it only unifies when both positions hold the same value. Returns the bindings dict or `None`
+  - Reworked propagation to carry partial-match **tokens** instead of bare facts: a new `Token` dataclass bundles the accumulated `facts` with the consistent `bindings`. `AlphaNode` emits a single-fact token per match; `BetaNode.join()` merges a left token with a right token, concatenating their facts in condition order and returning the merged token only when shared variables agree (conflicting values → `None`, no join). Terminal activations carry the full fact list and accumulated bindings through to the emitted match
+  - This fixes a P1 chained-join defect: rules with three or more conditions (e.g. `Person(?x)`, `Parent(?x, ?y)`, `Located(?y, ?z)`) previously lost bindings and accumulated wrong facts at the third join, and a conflicting third condition could spuriously fire. Beta nodes now keep both `left_tokens` and `right_tokens` memories and join each new token against every token on the opposite side, so deep chains stay binding-consistent and third-level conflicts are correctly suppressed
+  - Fixed an adjacent network-topology bug surfaced by the above: newly created beta nodes were never appended to their input nodes' `children`, so tokens could not propagate; propagation was reworked to support chained joins and to thread bindings end-to-end
+  - Reconciled with the rule-actions/provenance layer (#1096) merged after this fix was opened: `execute_matches()` still dedupes and fires `Rule.actions`/legacy `handler` through a bound `Reasoner` via `_make_activation_key`, now sourced from the Token model's own `bindings` instead of the interim `_bindings_for_rule()` regex re-extraction, which is removed as redundant
+  - New `tests/reasoning/test_rete_engine.py`: `unify_condition` unit cases (single/multi variable, literal args, predicate mismatch, repeated-variable equality), alpha match/reject, beta consistent-join vs conflict-reject, end-to-end rules (single-condition fires only the matching fact; multi-condition join fires only on consistent bindings), and a `TestThreeConditionChain` suite (valid three-condition match, third-level conflict suppression, insertion-order independence, `Match.facts` complete and in condition order, multiple left tokens joining one right fact, parity against `Reasoner._match_rule()`, and `reset()` clearing all token memory)
+
+- **KG provenance tests asserted on generated ID strings instead of stored records, and `kg_provenance.py` was missed by the `utcnow` sweep** (closes #946) by @pravit-amp
+  - The KG workflow and integration suites checked that a tracker call returned an ID matching a prefix (`assert cent_id.startswith("centrality_")`) without ever reading the record back, so an ID generator that returned a well-formed string and wrote nothing would have passed. Worse, some of those calls named tracker methods that do not exist anywhere in `semantica/` (`track_layer_analysis`, `track_centrality_score`), so the assertions were satisfied with no real interaction behind them
+  - Those tests now read provenance back through `get_provenance()` and assert on algorithm metadata, and call the methods that actually persist records. Verified by mutation rather than by a green run alone: neutering the manager's storage write (`self.storage.store(...)` → no-op) fails 10 tests
+  - `GraphBuilderWithProvenance` in `semantica/kg/kg_provenance.py` still stamped `activity_started_at_time`/`activity_ended_at_time` with the deprecated `datetime.utcnow()`; it was outside the `export/`+`provenance/` scope of the #1114 sweep below and now uses the same `utc_now_iso()` helper. `docs/guides/provenance.md` and `docs/reference/provenance.md` were still documenting `utcnow()` and a naive timestamp example, and now show the helper and the offset-bearing form
+  - 16 tests across the affected suites ended in `return <value>` instead of asserting, which pytest reports as `PytestReturnNotNoneWarning`; now zero
+
 - **The temporal-evolution `stability` metric was a hardcoded placeholder, not a duration**
   - `TemporalGraphQuery.analyze_evolution()` documents `stability` as a "relationship duration/stability measure", but the implementation appended a constant `1` for every relationship with both `valid_from` and `valid_until` set (`durations.append(1)  # Placeholder`). The reported stability was therefore always `1.0` when any bounded relationship existed and `0` otherwise — it never reflected how long relationships actually stayed valid, so it could not distinguish a graph of decade-long relationships from one of one-second relationships
   - `stability` now computes the mean valid-time duration in seconds (`(valid_until - valid_from).total_seconds()`) across relationships that have both bounds set. Relationships with a missing or open `valid_from`/`valid_until` are skipped (their duration is unbounded), and non-positive intervals are clamped to `0`; an empty set still reports `0`
@@ -121,6 +241,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - New `tests/export/test_timestamp_timezones.py` and `tests/provenance/test_timestamp_timezones.py`: offset presence on every export and provenance path, PROV-O literals valid as `xsd:dateTimeStamp`, comparison against a timezone-aware instant without `TypeError`, the Oxigraph filter that dropped the naive value (with a bound inside the indeterminate window, so the test cannot pass by accident), and the document `@id` remaining a valid IRI with `+00:00` in it. 11 of the 13 fail on the parent commit
   - **Fixed during review** (Qodo): once new entries carry `+00:00` and stored ones do not, `ProvenanceManager.query_recorded_between` and `audit_log` compared ISO timestamps as raw strings, so they ordered by spelling rather than by instant — an inclusive naive bound naming a stored offset-bearing timestamp sorted *below* it and dropped the record, and a bound written in another offset landed wherever its digits fell (`19:45+05:30` is 14:15Z, but sorted after 14:19Z). Both now compare instants through a new `to_utc_datetime()` helper that reads a missing offset as UTC, which is what the values written before this change actually were; a bound that cannot be read as a timestamp keeps the historical string comparison rather than raising on a call that used to work
   - The remaining 147 naive call sites are in `context/`, `vector_store/`, `seed/` and elsewhere, where timestamps are compared against values parsed from previously stored naive strings. Converting those without a read-side migration would raise `TypeError: can't compare offset-naive and offset-aware datetimes` on existing data, so they are deliberately left for a separate change
+- **`SHACLGenerator` mangles `#`-terminated namespaces into `#/`, so generated shapes target nothing** (#1082) by @changshenhan
+  - `__init__` normalized `base_uri` with `rstrip("/") + "/"`, which turns `http://example.org/manufacturing#` into `...manufacturing#/` — the most common RDF namespace convention. Every generated URI (`sh:targetClass`, `sh:path`, shape URIs) then landed in a different namespace than the instance data, and SHACL validation silently passed because the shapes targeted nothing
+  - `__init__` now preserves a namespace already ending in `/` or `#`, matching the `#`-aware normalization `generate()` already applies; `shapes_uri` inherits the fix
+  - New `test_hash_namespace_base_uri_is_not_mangled` in `tests/ontology/test_ontology_advanced.py` fails on the pre-fix normalization and passes with it; full ontology suite (76 tests) green
 
 - **`split`/chunking paths bypassed the centralized spaCy model cache, reloading the model on every call** (#1042, closes #998) by @Accute9, reviewed by @Sameer6305
   - `semantica/split/methods.py`'s `split_by_sentences()` and `semantica/split/semantic_chunker.py`'s `SemanticChunker.__init__` each called `spacy.load()` directly instead of reusing the process-level cache added in #889/`semantic_extract/methods.py`'s `load_spacy_model()` — every call/construction re-paid the ~120ms model-load cost independently of `NERExtractor`, which already used the cache

CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "Semantica: Graph-Native Infrastructure for Context and Accountable AI Systems"
+type: software
+authors:
+  - name: "Semantica"
+repository-code: "https://github.com/semantica-agi/semantica"
+url: "https://getsemantica.ai"
+license: MIT
+version: 0.6.7
+date-released: 2026-08-28
+keywords:
+  - knowledge-graph
+  - context-graph
+  - ai-agents
+  - llm
+  - decision-intelligence
+  - provenance
+  - explainability
+  - graph-rag

Dockerfile

@@ -1,5 +1,5 @@
 # syntax=docker/dockerfile:1
-FROM node:26-alpine AS frontend-builder
+FROM node:26-alpine@sha256:2d984a15c9b54fd0aeb608b8e0d0d83529eb34d2966db27a1fb4f1edc3d298a3 AS frontend-builder
 
 WORKDIR /app
 COPY explorer/package*.json ./explorer/
@@ -9,7 +9,18 @@ RUN npm ci
 COPY explorer/ ./
 RUN mkdir -p /app/semantica && npm run build
 
-FROM python:3.13-slim AS runtime
+# CVE-2026-14456 (OpenSSL QUIC-server DoS, flagged against this base image's
+# openssl/libssl3t64/openssl-provider-legacy): the Debian fix
+# (3.5.7-1~deb13u2) is only in trixie-proposed-updates as of this writing,
+# not yet promoted to trixie-security, so there's no package to pin here
+# today. Deliberately NOT running `apt-get upgrade` to chase it - that
+# breaks build reproducibility (terrascan AC_DOCKER_0052) and still
+# wouldn't reach a proposed-updates-only package. Once Debian ships the fix
+# and rebuilds this tag, the docker Dependabot ecosystem in
+# .github/dependabot.yml opens a PR bumping the digest pin above. Also: this
+# image only serves plain HTTP via uvicorn and never opens a QUIC listener,
+# so the bug isn't reachable here regardless.
+FROM python:3.14-slim@sha256:cae66f2ef0ec51a9891263eeee7f987dacf0a9879e8aa9353d5606e0530619a5 AS runtime
 
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
@@ -22,12 +33,35 @@ WORKDIR /app
 RUN groupadd --system semantica \
     && useradd --system --gid semantica --home-dir /app --shell /usr/sbin/nologin semantica
 
-COPY pyproject.toml README.md LICENSE MANIFEST.in ./
+COPY pyproject.toml README.md LICENSE MANIFEST.in \
+     .github/requirements/explorer-extra-py313.txt .github/requirements/pep517-build.txt ./
 COPY semantica/ ./semantica/
 COPY integrations/ ./integrations/
 COPY --from=frontend-builder /app/semantica/static ./semantica/static
 
-RUN pip install --no-cache-dir ".[explorer]" \
+# explorer-extra-py313.txt is `uv pip compile pyproject.toml --extra explorer
+# --python-version 3.13 --constraint requirements-ci.txt --generate-hashes`
+# (see ci.yml's explorer-extra-py311.txt for the CI counterpart, resolved
+# for CI's python 3.11 instead - the two aren't interchangeable: audioread
+# (via librosa) needs standard-aifc/standard-sunau only on python>=3.13,
+# since aifc/sunau left stdlib there, so a 3.11-resolved lockfile is
+# missing hashes pip needs on this image's actual 3.13 interpreter and
+# --require-hashes fails outright rather than silently under-pinning).
+# Every fetched package is hash-verified (Scorecard Pinned-Dependencies)
+# and pinned to the same versions CI audited, e.g. msgpack==1.2.1 and
+# setuptools==84.0.0 (which also replaces the base image's vulnerable
+# 70.3.0, CVE-2025-47273 - nothing else in the tree pulls a newer copy).
+# --no-deps on the local package itself: it's our own source tree, not a
+# fetch, so there's nothing to hash-pin there - but `pip install .` still
+# does a PEP 517 build, which by default creates an *isolated* build env
+# and fetches [build-system] requires (setuptools, wheel) completely
+# outside any hash checking. pep517-build.txt pins that exact
+# build-system.requires; installing it first and passing
+# --no-build-isolation makes pip reuse those hash-verified copies instead
+# of fetching its own.
+RUN pip install --no-cache-dir -r explorer-extra-py313.txt -r pep517-build.txt --require-hashes \
+    && pip install --no-cache-dir --no-deps --no-build-isolation . \
+    && rm -f explorer-extra-py313.txt pep517-build.txt \
     && chown -R semantica:semantica /app
 
 USER semantica

GROWTH.md

@@ -0,0 +1,131 @@
+# Growth & Distribution Playbook
+
+North star: **10,000 developers who actually use Semantica in real projects**, not a raw PyPI download number. Downloads are a lagging indicator of distribution, not a target to optimize directly.
+
+```
+GitHub stars → Website visitors → PyPI installs → Weekly active users → Production deployments → Enterprise customers
+```
+The last two matter far more than the download count.
+
+## Guardrails — do not do this
+
+- No fake/looping CI jobs that repeatedly `pip install semantica` purely to inflate the graph. It's detectable, it produces zero real users, and it damages credibility with anyone doing diligence (investors, enterprise buyers, security reviewers).
+- No package-splitting purely to multiply install counts — only split into `semantica-*` packages when there's a real architectural reason.
+- No meaningless Docker pulls or notebook launches with no real content behind them.
+- Every item below should get someone from "installed it" to "used it for something real." If a channel can't do that, it's not worth building.
+
+## 30-day priority sprint
+
+Ordered by leverage-to-effort ratio; do these first.
+
+| # | Initiative | Target |
+| - | ---------- | ------ |
+| 1 | ✅ GitHub Actions example + reusable `setup-semantica` composite action + install-matrix badge | done |
+| 2 | Google Colab notebooks | 10 |
+| 3 | Docker images (RAG, Graph, Agent, API) | 4-5 |
+| 4 | Hugging Face Spaces demos | 3-4 |
+| 5 | LangChain integration + example | 1 |
+| 6 | LlamaIndex integration + example | 1 |
+| 7 | Vector/graph DB integrations (Qdrant, Weaviate, Neo4j) | 3 |
+| 8 | MCP server + example | 1 (already have `mcp/` — package as a distributable example) |
+| 9 | Production-quality starter repos (FastAPI, Streamlit, Gradio) | 3 |
+| 10 | `awesome-rag` / `awesome-llm` / `awesome-knowledge-graph` list submissions | 3+ PRs |
+
+Push everything through: GitHub → Discord (`sV34vps5hH`) → X (`@BuildSemantica`) → GitHub Discussions → Reddit → Hacker News → relevant newsletters.
+
+## Full channel checklist
+
+### CI/CD (highest-intent distribution — installs tied to real pipelines)
+
+- [x] GitHub Actions example in `examples/ci/github-actions.yml`
+- [x] Reusable composite GitHub Action — [`.github/actions/setup-semantica`](.github/actions/setup-semantica/action.yml), modeled on `actions/setup-python`; usable by any repo as `uses: semantica-agi/semantica/.github/actions/setup-semantica@main`
+- [x] "pip install" status badge in the README, backed by [`.github/workflows/install-matrix.yml`](.github/workflows/install-matrix.yml) — verifies the *published* package installs cleanly on Ubuntu/macOS/Windows across Python 3.9-3.12, weekly + on every release
+- [x] GitLab CI template — `examples/ci/gitlab-ci.yml`
+- [x] CircleCI template — `examples/ci/circleci-config.yml`
+- [ ] Jenkins, Azure DevOps, Bitbucket Pipelines, Buildkite, Travis CI equivalents
+
+### Release pipeline hardening (already had Trusted Publishing/OIDC + SLSA attestation — this rounds it out to match top-tier OSS release practice)
+
+- [x] `twine check` gate in `.github/workflows/release.yml` before publish — catches a broken PyPI long-description render before it goes live instead of after (a malformed README on the live PyPI page is a silent conversion killer)
+- [x] `CITATION.cff` (see Academic & research below)
+- [x] OpenSSF Scorecard (see Discoverability below)
+- [ ] Considered and deliberately skipped: Release Drafter / auto-generated changelogs — this repo hand-curates `CHANGELOG.md` with far more detail (PR numbers, contributors, phase-1 limitations) than a bot would produce. Don't introduce this without checking with maintainers first.
+- [ ] Renovate / Dependabot config templates that auto-bump the `semantica` version in downstream repos — real recurring CI runs on real adopters
+- [ ] Nightly scheduled workflow template that tests a downstream project against `semantica@latest`
+
+### Containers & dev environments
+
+- [ ] Official Docker images: RAG, Graph, Agent, API, `+Postgres`, `+Neo4j`, `+Qdrant`
+- [ ] `docker-compose` examples (repo already has `docker-compose.dev.yml` / `docker-compose.yml` as a base)
+- [ ] `.devcontainer/devcontainer.json` for one-click "Reopen in Container"
+- [ ] GitHub Codespaces-ready config
+- [ ] Gitpod config
+- [ ] "Use this template" GitHub repo button so new projects start with `semantica` in `requirements.txt`
+
+### Notebooks & hosted demos
+
+- [ ] 10-20 Google Colab notebooks (Graph RAG, agent memory, entity resolution, semantic search, document intelligence)
+- [ ] Kaggle Notebooks/Kernels
+- [ ] Binder / mybinder.org config for instant repo launch
+- [ ] SageMaker Studio Lab / Databricks Community Edition / Paperspace Gradient examples
+- [ ] Hugging Face Spaces (Streamlit/Gradio) demos with `semantica` in `requirements.txt`
+- [ ] Public hosted playground (source on GitHub, install visible)
+
+### Framework & data-store integrations
+
+- [x] LangChain integration — `integrations/langchain/` (`SemanticaRetriever`, `SemanticaVectorStore`, `SemanticaKGTool`/`SemanticaDecisionTool`), `pip install semantica[langchain]`, shipped in 0.6.7
+- [ ] LlamaIndex integration + example
+- [ ] LangGraph example
+- [ ] Neo4j integration/example (docs already list it as a supported graph store — turn into a runnable example repo)
+- [ ] Vector DB examples: Qdrant, Weaviate, Milvus, Pinecone, Chroma, FAISS, pgvector, OpenSearch/Elasticsearch (FAISS/Pinecone/Weaviate/Qdrant/Milvus/PgVector already supported per `docs/community-projects.md` — package each as a standalone example)
+- [ ] LLM provider quickstarts: OpenAI, Anthropic, Gemini, Groq, Ollama, HuggingFace, DeepSeek, LiteLLM (already-supported providers per docs — each gets its own copy-paste quickstart)
+- [ ] CrewAI / Agno integration examples (already documented under `docs/integrations/`) — promote as standalone repos, not just docs pages
+
+### Package managers & installers
+
+- [ ] conda-forge feedstock
+- [ ] Homebrew formula for the CLI
+- [ ] Nix/nixpkgs packaging
+- [ ] Chocolatey / Scoop (Windows)
+- [ ] Document `uv add semantica` and `poetry add semantica` explicitly alongside `pip install`
+
+### Downstream packages & CLI
+
+- [ ] Genuinely useful `semantica-*` packages only where warranted (e.g. `semantica-rag`, `semantica-connectors`) — each pulls `semantica` as a real dependency
+- [ ] Make sure `semantica init / ingest / index / query / serve` CLI flows are the default onboarding path in every tutorial
+- [ ] VS Code extension wrapping the CLI (scaffold + run commands from the command palette)
+- [ ] JetBrains plugin equivalent
+
+### Templates & starters
+
+- [ ] Cookiecutter templates: `cookiecutter-semantic-rag`, `cookiecutter-ai-agent`, `cookiecutter-enterprise-rag`
+- [ ] Starter repos: FastAPI, Streamlit, Gradio, Next.js frontend + Semantica backend
+- [ ] Cloud deploy templates: AWS, GCP, Azure, Modal, Railway, Render, Fly.io (repo already has `deploy/azure`, `deploy/gcp`, `deploy/fly`, `deploy/railway`, `deploy/render`, `deploy/kubernetes`, `deploy/helm` — link these prominently from the README/quickstart, they're already-built distribution surface)
+- [ ] Terraform / Pulumi / Helm modules published to their respective registries
+
+### Discoverability & curation
+
+- [ ] Submit to `awesome-rag`, `awesome-llm`, `awesome-knowledge-graph`, `awesome-python`
+- [ ] Pitch newsletters with engaged Python/AI audiences (Python Weekly, Import AI, TLDR AI, etc.)
+- [x] PyPI trove classifiers/keywords and `project.urls` (Homepage/Docs/Repository/Changelog/Bug Tracker) — already complete in `pyproject.toml`
+- [ ] Get listed on Papers With Code for any retrieval/graph-RAG benchmark work
+- [x] [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/semantica-agi/semantica) badge + weekly workflow (`.github/workflows/scorecard.yml`) — a concrete trust signal security/procurement teams check before greenlighting adoption, which gates real (non-CI-bot) install growth at enterprises
+
+### Academic & research
+
+- [x] `CITATION.cff` at repo root — enables GitHub's native "Cite this repository" button, feeds Google Scholar/academic tooling; complements `docs/citation.md` (still needs a real Zenodo DOI to replace the `XXXXXXX` placeholder in both places once one is minted)
+- [ ] arXiv paper if there's real architectural novelty to describe
+- [ ] Zenodo DOI for citability (`docs/citation.md` already exists — make sure it points to a real DOI)
+- [ ] Workshop/tutorial sessions at PyData/ODSC-style events with hands-on install steps
+- [ ] University course material / bootcamp adoption outreach
+
+### Content
+
+- [ ] Reproducible benchmark repos (Graph RAG vs vector RAG, retrieval@k, enterprise-scale retrieval) with `pip install semantica && python benchmark.py`
+- [ ] 20-30 real-world example applications (RAG, enterprise document intelligence, financial entity graphs, code knowledge graphs, research discovery, agent memory)
+- [ ] Blog/tutorial posts on Dev.to, Medium, personal blogs — always with runnable code, not just prose
+- [ ] Contribute integrations/PRs to other projects building RAG/agents/knowledge graphs — "I implemented Semantica support" beats "please use Semantica"
+
+## Tracking
+
+Don't just watch the raw PyPI number — use download analytics (e.g. PePy) to separate CI/bot traffic from real installs, and track the funnel above end-to-end where possible (stars → site visits → installs → weekly actives).

README.md

@@ -26,7 +26,7 @@
 
 #### Built for High-Stakes, Regulated Domains
 
-[![GitHub Stars](https://img.shields.io/github/stars/semantica-agi/semantica?style=flat-square&color=FFD700&logo=github&logoColor=white&label=Stars)](https://github.com/semantica-agi/semantica) [![GitHub Forks](https://img.shields.io/github/forks/semantica-agi/semantica?style=flat-square&color=6E40C9&logo=github&logoColor=white&label=Forks)](https://github.com/semantica-agi/semantica/network/members) [![Contributors](https://img.shields.io/github/contributors/semantica-agi/semantica?style=flat-square&color=2EA043&logo=github&logoColor=white)](https://github.com/semantica-agi/semantica/graphs/contributors) [![PyPI](https://img.shields.io/pypi/v/semantica.svg?style=flat-square&color=0066CC&logo=pypi&logoColor=white)](https://pypi.org/project/semantica/) [![Total Downloads](https://static.pepy.tech/badge/semantica?style=flat-square)](https://pepy.tech/project/semantica) [![Python 3.8+](https://img.shields.io/badge/python-3.8+-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT) [![CI](https://img.shields.io/github/actions/workflow/status/semantica-agi/semantica/ci.yml?style=flat-square&label=CI)](https://github.com/semantica-agi/semantica/actions) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/semantica-agi/semantica)
+[![GitHub Stars](https://img.shields.io/github/stars/semantica-agi/semantica?style=flat-square&color=FFD700&logo=github&logoColor=white&label=Stars)](https://github.com/semantica-agi/semantica) [![GitHub Forks](https://img.shields.io/github/forks/semantica-agi/semantica?style=flat-square&color=6E40C9&logo=github&logoColor=white&label=Forks)](https://github.com/semantica-agi/semantica/network/members) [![Contributors](https://img.shields.io/github/contributors/semantica-agi/semantica?style=flat-square&color=2EA043&logo=github&logoColor=white)](https://github.com/semantica-agi/semantica/graphs/contributors) [![PyPI](https://img.shields.io/pypi/v/semantica.svg?style=flat-square&color=0066CC&logo=pypi&logoColor=white)](https://pypi.org/project/semantica/) [![Total Downloads](https://static.pepy.tech/badge/semantica?style=flat-square)](https://pepy.tech/project/semantica) [![Python 3.8+](https://img.shields.io/badge/python-3.8+-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT) [![CI](https://img.shields.io/github/actions/workflow/status/semantica-agi/semantica/ci.yml?style=flat-square&label=CI)](https://github.com/semantica-agi/semantica/actions) [![Install Matrix](https://img.shields.io/github/actions/workflow/status/semantica-agi/semantica/install-matrix.yml?style=flat-square&label=pip%20install)](https://github.com/semantica-agi/semantica/actions/workflows/install-matrix.yml) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/semantica-agi/semantica/badge?style=flat-square)](https://scorecard.dev/viewer/?uri=github.com/semantica-agi/semantica) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/semantica-agi/semantica)
 
 [![Website](https://img.shields.io/badge/Website-getsemantica.ai-000000?style=flat-square&logo=googlechrome&logoColor=white)](https://getsemantica.ai/) [![Docs](https://img.shields.io/badge/Docs-docs.getsemantica.ai-0099FF?style=flat-square&logo=readthedocs&logoColor=white)](https://docs.getsemantica.ai/) [![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/sV34vps5hH) [![Twitter/X](https://img.shields.io/badge/Follow-%40BuildSemantica-000000?style=flat-square&logo=x&logoColor=white)](https://x.com/BuildSemantica) [![YouTube](https://img.shields.io/badge/YouTube-Watch%20Demos-FF0000?style=flat-square&logo=youtube&logoColor=white)](https://www.youtube.com/watch?v=QfnNZg4-dZA) [![Changelog](https://img.shields.io/badge/Changelog-View-6E40C9?style=flat-square&logo=keepachangelog&logoColor=white)](CHANGELOG.md)
 
@@ -87,7 +87,7 @@ Semantica sits underneath your LLM, vector store, and agent framework as a deter
 - **Graph Analytics:** Centrality, community detection, link prediction, and shortest-path queries over the graph you just built
 - **Polyglot Graph Storage:** Native RDF (embedded Oxigraph, Blazegraph, Apache Jena, Eclipse RDF4J via SPARQL) and Labeled Property Graphs (Neo4j, FalkorDB, Apache AGE, AWS Neptune via Cypher), plus vector stores, all swappable without touching your code
 - **Visualization:** Explore any graph, ontology, or timeline in an interactive browser workbench
-- **Drop-in Integrations:** Native Agno and CrewAI support, a full-featured MCP server, a comprehensive CLI, a REST API, and plugins across major editors
+- **Drop-in Integrations:** Native Agno, CrewAI, and LangChain support, a full-featured MCP server, a comprehensive CLI, a REST API, and plugins across major editors
 
 ---
 
@@ -142,11 +142,13 @@ compliant = graph.check_decision_rules({"category": "vendor_selection"})  # poli
 ```bash
 semantica doctor
 # Python 3.11.9         pass
-# semantica 0.6.6       pass
+# semantica 0.6.7       pass
 # faiss vector store    pass
 # Config file           pass    ~/.semantica/config.yaml
 ```
 
+**Running in a script or CI?** Progress bars are written only when stdout is an interactive terminal (or a Jupyter notebook), so piping and redirecting stay clean by default. Override with `SEMANTICA_DISABLE_PROGRESS=1` to silence progress everywhere, or `SEMANTICA_FORCE_PROGRESS=1` to keep it when stdout is redirected. `SEMANTICA_DISABLE_PROGRESS` takes precedence.
+
 <div align="center">
 
 If Semantica solves a real problem for you, a star helps others find it.
@@ -1186,7 +1188,7 @@ Start with `semantica`, verify with `doctor`, build a graph, and explore the com
 
 ## Integrations
 
-Native plugin bundles for Claude Code, Cursor, Codex, Windsurf, Cline, Continue, VS Code, and OpenClaw; a full-featured MCP server for any MCP-compatible client; a comprehensive REST API; and first-class Agno and CrewAI support for agentic frameworks. Every major LLM provider is already supported via `semantica.llms` and LiteLLM: OpenAI, Anthropic, Gemini, Mistral, Llama, Groq, Cohere, Azure, Bedrock, Ollama, DeepSeek, HuggingFace, and more.
+Native plugin bundles for Claude Code, Cursor, Codex, Windsurf, Cline, Continue, VS Code, and OpenClaw; a full-featured MCP server for any MCP-compatible client; a comprehensive REST API; and first-class Agno, CrewAI, and LangChain support for agentic frameworks. Every major LLM provider is already supported via `semantica.llms` and LiteLLM: OpenAI, Anthropic, Gemini, Mistral, Llama, Groq, Cohere, Azure, Bedrock, Ollama, DeepSeek, HuggingFace, and more.
 
 MCP setup takes 30 seconds — see [MCP Server](#mcp-server) below.
 
@@ -1305,17 +1307,17 @@ MCP setup takes 30 seconds — see [MCP Server](#mcp-server) below.
 <strong>CrewAI</strong><br/>
 <sub>First-class · <code>pip install semantica[crewai]</code></sub>
 </td>
+<td align="center" width="12.5%">
+<a href="https://github.com/langchain-ai/langchain"><img src="https://github.com/langchain-ai.png?size=120" alt="LangChain" width="48" height="48" /></a><br/>
+<strong>LangChain</strong><br/>
+<sub>First-class · <code>pip install semantica[langchain]</code></sub>
+</td>
 </tr>
 <tr>
 <th colspan="8" align="left">Already Supported via REST API &amp; MCP</th>
 </tr>
 <tr>
 <td align="center" width="12.5%">
-<a href="https://github.com/langchain-ai/langchain"><img src="https://github.com/langchain-ai.png?size=120" alt="LangChain" width="48" height="48" /></a><br/>
-<strong>LangChain</strong><br/>
-<sub>REST API · MCP</sub>
-</td>
-<td align="center" width="12.5%">
 <a href="https://github.com/langchain-ai/langgraph"><img src="https://github.com/langchain-ai.png?size=120" alt="LangGraph" width="48" height="48" /></a><br/>
 <strong>LangGraph</strong><br/>
 <sub>REST API · MCP</sub>
@@ -1346,11 +1348,6 @@ MCP setup takes 30 seconds — see [MCP Server](#mcp-server) below.
 </tr>
 <tr>
 <td align="center" width="12.5%">
-<a href="https://github.com/langchain-ai/langchain"><img src="https://github.com/langchain-ai.png?size=120" alt="LangChain" width="48" height="48" /></a><br/>
-<strong>LangChain</strong><br/>
-<sub>Dedicated toolkit</sub>
-</td>
-<td align="center" width="12.5%">
 <a href="https://github.com/run-llama/llama_index"><img src="https://github.com/run-llama.png?size=120" alt="LlamaIndex" width="48" height="48" /></a><br/>
 <strong>LlamaIndex</strong><br/>
 <sub>Dedicated toolkit</sub>
@@ -1466,18 +1463,18 @@ For contributor / dev-server setup: **[explorer/README.md: Local Setup Guide](ex
 
 ---
 
-## What's New in v0.6.6
+## What's New in v0.6.7
 
-**Security release — upgrading is strongly recommended.** Fixes for a privately disclosed batch of vulnerabilities spanning backup/restore, database export, outbound requests, and triplet-store backends, plus SSRF hardening across ingestion:
+**Feature release**, plus one SSRF hardening fix and a large batch of correctness fixes across the RDF/ontology export pipeline:
 
-- **Tarball restore path traversal**: `semantica backup restore` now validates every archive member for path containment and rejects symlink/hardlink escapes before extraction
-- **Latent SQL injection in `DataExporter.export_table_data()`**: table/schema names are now identifier-allowlisted and `where`/`order_by` fragments are blocklist-checked
-- **DNS-rebinding TOCTOU in the shared SSRF guard**: the resolved IP that passes validation is now the one the connection is pinned to, closing the check-then-use race (also closes the `100.64.0.0/10` CGNAT gap)
-- **Stored XSS in HTML report generation** and **unvalidated SPARQL object IRIs in AnzoStore** (SPARQL injection): both now escape/validate before interpolation
-- **`Authorization`/`Proxy-Authorization` credential leakage across redirects**, plus **SSRF gaps in `FeedIngestor`/`FeedMonitor`, `RepoIngestor`, and the MCP/public-API ingest paths**: all now route through the shared, redirect-safe SSRF guard
-- **HTTP response header injection and an unbounded-memory DoS** in the Explorer API, and a **`fastapi`/`python-multipart` ReDoS** (PYSEC-2024-38): floors raised, inputs sanitized, candidate pools capped
+- **First-class LangChain integration** (`semantica[langchain]`): a `BaseRetriever` and `VectorStore` over `HybridSearch`, plus graph/decision-query tools
+- **SAP OData ingestor** (`semantica[ingest-sap]`): OAuth2/Basic-auth, SSRF-guarded ingestion for Business Partners and Sales Orders, following the existing Snowflake/Databricks connector pattern
+- **`ContextGraph` gains deterministic, human-editable Markdown round-trip persistence** alongside the existing JSON API, and the Explorer graph inspector gains a read-only Markdown content viewer
+- **`reasoning` gains a structured Action layer**: rule-driven `Assert`/`Retract`/`Call`/`EmitEvent` actions with optional provenance, turning the reasoner into a production-rule system
+- **`run_shacl_validation` is now a public, documented API**, and a dozen ontology/RDF export correctness fixes land: OWL property/class export, SHACL target-namespace resolution, one canonical confidence datatype across all four RDF formats, reachable OWL-Time reification, JSON-LD default-graph and content-derived document identity, and full metadata passthrough on every RDF serializer
+- **Security**: Agno's `AgnoKnowledgeGraph.load_urls()` and OpenClaw's MCP tool now route outbound requests through the shared SSRF guard
 
-Also ships: **first-class CrewAI integration** (`semantica[crewai]`, extraction/decision tools + a knowledge source), **`ContextGraph` retraction and purge** (GDPR-style erasure without a full `clear()`), a declared **Semantica RDF vocabulary with deterministic entity/relationship IRIs** (stable, diffable exports), and **timezone-aware timestamps** across `export/` and `provenance/`.
+Also fixes: `PipelineBuilder.set_parallelism()` now actually parallelizes independent pipeline steps, `flatten_dict()` no longer silently drops data on a key collision, `Config.get()` honors boolean environment overrides, and the MCP server's `export_graph` tool works again on every format.
 
 → [Full release notes](RELEASE_NOTES.md) · [Changelog](CHANGELOG.md)
 
@@ -1509,6 +1506,7 @@ pip install semantica[all]      # everything
 ```bash
 pip install semantica[agno]                 # Agno multi-agent integration
 pip install semantica[crewai]               # CrewAI integration
+pip install semantica[langchain]            # LangChain / LangGraph integration
 pip install semantica[llm-litellm]          # OpenAI, Anthropic, Gemini, Mistral, Llama, Groq, Cohere, Bedrock, Ollama, DeepSeek, and more
 pip install semantica[graph-neo4j]          # Neo4j graph store (LPG)
 pip install semantica[graph-falkordb]       # FalkorDB graph store (LPG)
@@ -1536,6 +1534,20 @@ git clone https://github.com/semantica-agi/semantica.git
 cd semantica && pip install -e ".[dev]" && pytest tests/
 ```
 
+### CI & Deployment
+
+Wiring `semantica` into your own CI is a two-minute job. On GitHub Actions, use the reusable composite action:
+
+```yaml
+- uses: semantica-agi/semantica/.github/actions/setup-semantica@main
+  with:
+    python-version: '3.11'
+```
+
+Copy-paste starting templates for GitHub Actions, GitLab CI, and CircleCI live in [examples/ci/](examples/ci/). The published package itself is verified installable across Ubuntu/macOS/Windows and Python 3.9-3.12 every week by the [Install Matrix workflow](.github/workflows/install-matrix.yml).
+
+Ready-made deployment configs for AWS, GCP, Azure, Fly.io, Railway, Render, Kubernetes, and Helm are in [deploy/](deploy/).
+
 ---
 
 ## Enterprise
@@ -1561,11 +1573,11 @@ On-premises deployment · Private cloud · Custom domain implementations · SLA-
 
 ## Star History
 
-<a href="https://www.star-history.com/?repos=semantica-agi%2Fsemantica&type=date&legend=top-left">
+<a href="https://star-history.dera.page/#semantica-agi/semantica&amp;type=date&amp;legend=top-left">
  <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=semantica-agi/semantica&type=date&theme=dark&legend=top-left" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=semantica-agi/semantica&type=date&legend=top-left" />
-   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=semantica-agi/semantica&type=date&legend=top-left" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=semantica-agi/semantica&amp;type=date&amp;theme=dark&amp;legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=semantica-agi/semantica&amp;type=date&amp;legend=top-left" />
+   <img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=semantica-agi/semantica&amp;type=date&amp;legend=top-left" />
  </picture>
 </a>
 

cookbook/introduction/22_Provenance_Tracking.ipynb

@@ -0,0 +1,253 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Provenance Tracking (W3C PROV-O)\n",
+    "\n",
+    "## Overview\n",
+    "\n",
+    "In high-stakes domains — healthcare, legal, finance, research — a Knowledge Graph is only as trustworthy as its ability to answer **\"where did this fact come from?\"**. Semantica's `provenance` module provides audit-grade, W3C PROV-O-aligned tracking for every entity, relationship and chunk that flows through your pipeline.\n",
+    "\n",
+    "In this cookbook you will learn how to:\n",
+    "\n",
+    "- Track entities and relationships with **source details** (DOI, page, verbatim quote, confidence)\n",
+    "- Walk the full **lineage** of a fact (document → chunk → entity → KG)\n",
+    "- Audit **revision history** and **all sources** behind an entity\n",
+    "- **Invalidate** a fact without deleting it (prov:Invalidation) — corrections stay provable\n",
+    "- Verify **tamper-evidence** with chained SHA-256 checksums\n",
+    "\n",
+    "**The Scenario:** a research team ingests findings from two scientific papers (with DOIs) into a Knowledge Graph. A regulator later asks: *\"Which paper, which figure, and which exact sentence supports the claim that fish biomass increased by 463%? And was that fact ever corrected?\"*"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!pip install -q semantica"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import json\n",
+    "from semantica.provenance import (\n",
+    "    ProvenanceManager,\n",
+    "    compute_checksum,\n",
+    "    verify_checksum,\n",
+    ")\n",
+    "\n",
+    "# In-memory storage for this demo; pass storage_path=\"provenance.db\"\n",
+    "# (or a config with provenance.storage_path) for a persistent SQLite backend.\n",
+    "prov = ProvenanceManager()\n",
+    "print(\"ProvenanceManager ready (in-memory storage)\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 1: Track Entities with Audit-Grade Source Details\n",
+    "\n",
+    "Every fact we ingest carries its evidence with it: the **source identifier** (a DOI here), the **location** inside the source (a figure), the **verbatim quote**, and the extractor's **confidence**."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Finding from paper #1\n",
+    "entry_biomass = prov.track_entity(\n",
+    "    entity_id=\"claim_biomass_increase\",\n",
+    "    source=\"DOI:10.1371/journal.pone.0023601\",\n",
+    "    confidence=0.92,\n",
+    "    source_location=\"Figure 2\",\n",
+    "    source_quote=\"Total fish biomass increased by 463% ...\",\n",
+    ")\n",
+    "\n",
+    "# Supporting entity from paper #2\n",
+    "entry_reserve = prov.track_entity(\n",
+    "    entity_id=\"marine_reserve_1\",\n",
+    "    source=\"DOI:10.1126/science.1088121\",\n",
+    "    confidence=0.88,\n",
+    "    source_location=\"Table 1\",\n",
+    "    source_quote=\"... no-take marine reserve at Cabo Pulmo ...\",\n",
+    ")\n",
+    "\n",
+    "print(\"Tracked:\", entry_biomass.entity_id, \"|\", entry_reserve.entity_id)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 2: Track the Relationship Between Facts\n",
+    "\n",
+    "Facts rarely stand alone. The claim about biomass increase is *about* the marine reserve — that relationship is a first-class provenance-tracked object too.\n",
+    "\n",
+    "`track_relationship()` has no dedicated subject/object fields, so by convention we record which two entities it connects inside `metadata`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rel = prov.track_relationship(\n",
+    "    relationship_id=\"rel_biomass_about_reserve\",\n",
+    "    source=\"DOI:10.1371/journal.pone.0023601\",\n",
+    "    metadata={\n",
+    "        \"type\": \"measured_at\",\n",
+    "        # No dedicated endpoint fields on track_relationship() yet -- record\n",
+    "        # which entities this relationship connects here by convention.\n",
+    "        \"subject_entity_id\": \"claim_biomass_increase\",\n",
+    "        \"object_entity_id\": \"marine_reserve_1\",\n",
+    "    },\n",
+    ")\n",
+    "\n",
+    "print(\"Relationship tracked:\", rel.entity_id, \"|\", rel.metadata[\"subject_entity_id\"], \"->\", rel.metadata[\"object_entity_id\"])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 3: Walk the Lineage\n",
+    "\n",
+    "`get_lineage` reconstructs everything known about a fact; `trace_lineage` returns the ordered chain of `ProvenanceEntry` records — every version, every activity, every agent that touched it."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "lineage = prov.get_lineage(\"claim_biomass_increase\")\n",
+    "print(json.dumps(lineage, indent=2, default=str)[:800])\n",
+    "\n",
+    "print(\"\\n--- ordered chain ---\")\n",
+    "for e in prov.trace_lineage(\"claim_biomass_increase\"):\n",
+    "    print(f\"{e.entity_id} | seq#{e.sequence_id} | {e.activity_id}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 4: Audit Sources and Revision History\n",
+    "\n",
+    "When the regulator asks *\"has this fact ever been corrected?\"*, `revision_history` answers with the full version chain, and `get_all_sources` lists every source document that ever supported the entity."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "revisions = prov.revision_history(\"claim_biomass_increase\")\n",
+    "print(f\"{len(revisions)} revision(s) on record\")\n",
+    "\n",
+    "for s in prov.get_all_sources(\"claim_biomass_increase\"):\n",
+    "    print(\"source:\", s)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 5: Invalidate — Correct Without Deleting\n",
+    "\n",
+    "Suppose paper #1 is retracted in part. An audit trail must **not** silently delete the fact: `invalidate` archives the pre-invalidation state and appends a fresh `prov:Invalidation` entry naming **who** retracted it and **why**."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "invalidated = prov.invalidate(\n",
+    "    entity_id=\"claim_biomass_increase\",\n",
+    "    agent_id=\"reviewer_dr_chen\",\n",
+    "    reason=\"Partial retraction: Figure 2 statistics corrected by publisher (see erratum).\",\n",
+    ")\n",
+    "print(\"Invalidated:\", invalidated.entity_id, \"| invalidated flag:\", getattr(invalidated, \"invalidated\", True))\n",
+    "\n",
+    "stats = prov.get_statistics()\n",
+    "print(\"\\nStorage statistics:\", json.dumps(stats, indent=2, default=str))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 6: Verify Tamper-Evidence\n",
+    "\n",
+    "Each entry carries a deterministic SHA-256 checksum chained to the previous entry. Recompute and compare to detect any after-the-fact corruption of the provenance record."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# entry_biomass was returned by track_entity in Step 1\n",
+    "ok = verify_checksum(entry_biomass)\n",
+    "print(\"Checksum verified:\", ok)\n",
+    "\n",
+    "print(\"Computed:\", compute_checksum(entry_biomass)[:16], \"...\")\n",
+    "print(\"Stored:  \", entry_biomass.checksum[:16] if getattr(entry_biomass, 'checksum', None) else \"(see entry fields)\")\n",
+    "chain = prov.verify_chain()\n",
+    "print(\"Chain verification:\", json.dumps(chain, default=str)[:200])\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Summary\n",
+    "\n",
+    "| Need | Call |\n",
+    "|---|---|\n",
+    "| Record a fact's evidence | `prov.track_entity(entity_id, source, confidence=..., source_location=..., source_quote=...)` |\n",
+    "| Record a relationship | `prov.track_relationship(relationship_id, source, metadata=...)` |\n",
+    "| Full lineage of a fact | `prov.get_lineage(entity_id)` / `prov.trace_lineage(entity_id)` |\n",
+    "| \"Was it ever corrected?\" | `prov.revision_history(entity_id)` |\n",
+    "| \"Which sources support it?\" | `prov.get_all_sources(entity_id)` |\n",
+    "| Retract without deleting | `prov.invalidate(entity_id, agent_id, reason=...)` |\n",
+    "| Tamper check | `verify_checksum(entry)` |\n",
+    "\n",
+    "### Where to go next\n",
+    "\n",
+    "- **Conflict Detection and Resolution** (notebook 17) — what happens when two sources disagree.\n",
+    "- **Your First Knowledge Graph** (notebook 08) — plug `provenance=True` into extractors so tracking happens automatically during ingestion.\n",
+    "- The module docstring (`help(semantica.provenance)`) documents opt-in integration with `kg`, `split` and `conflicts` trackers."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

cookbook/introduction/23_Reasoning.ipynb

@@ -0,0 +1,383 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "b76a5997",
+   "metadata": {},
+   "source": [
+    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/semantica-agi/semantica/blob/main/cookbook/introduction/23_Reasoning.ipynb)\n",
+    "\n",
+    "# Reasoning Module — Practical Guide\n",
+    "\n",
+    "Semantica's `reasoning` module derives new knowledge from existing facts and knowledge graphs. It ships several strategies behind one facade:\n",
+    "\n",
+    "- **`Reasoner`** — unified facade with forward chaining, backward chaining, and one-shot `infer_facts`\n",
+    "- **`DatalogReasoner`** — semi-naive Datalog fixpoint evaluation with variable queries\n",
+    "- **`ExplanationGenerator`** — human-readable explanations and reasoning paths for inferred conclusions\n",
+    "- Plus lower-level engines: `ReteEngine`, `SPARQLReasoner`, `GraphReasoner`, temporal reasoning\n",
+    "\n",
+    "This notebook walks through the facade, the Datalog engine, and explanations. All APIs are verified against `semantica/reasoning/`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "52073af7",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:45:55.427457Z",
+     "iopub.status.busy": "2026-08-26T18:45:55.427247Z",
+     "iopub.status.idle": "2026-08-26T18:45:57.266607Z",
+     "shell.execute_reply": "2026-08-26T18:45:57.264783Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "!pip install -q semantica"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "06deb916",
+   "metadata": {},
+   "source": [
+    "## 1) Forward chaining with the `Reasoner` facade\n",
+    "\n",
+    "Facts are simple `Predicate(args)` strings. Rules use `IF <conditions> THEN <conclusion>` with `?x`-style variables. `forward_chain()` derives everything possible and returns a list of `InferenceResult` objects."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "519ca92d",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:45:57.270791Z",
+     "iopub.status.busy": "2026-08-26T18:45:57.270352Z",
+     "iopub.status.idle": "2026-08-26T18:45:59.991941Z",
+     "shell.execute_reply": "2026-08-26T18:45:59.990678Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "<div style='font-family: monospace;'><h4>🧠 Semantica - 📊 Current Progress</h4><table style='width: 100%; border-collapse: collapse;'><tr><th>Status</th><th>Action</th><th>Module</th><th>Submodule</th><th>Progress</th><th>ETA</th><th>Rate</th><th>Time</th><th>Extracted</th></tr><tr><td>✅</td><td>Semantica is reasoning</td><td>🤔 reasoning</td><td>Reasoner</td><td>100.0%</td><td>-</td><td>-</td><td>0.00s</td><td>-</td></tr><tr><td>✅</td><td>Semantica is reasoning</td><td>🤔 reasoning</td><td>DatalogReasoner</td><td>100.0%</td><td>-</td><td>-</td><td>0.00s</td><td>-</td></tr><tr><td>✅</td><td>Semantica is reasoning</td><td>🤔 reasoning</td><td>ExplanationGenerator</td><td>100.0%</td><td>-</td><td>-</td><td>0.00s</td><td>-</td></tr></table></div>"
+      ],
+      "text/plain": [
+       "<IPython.core.display.HTML object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "🔄 Semantica is reasoning: Performing forward chaining 🤔 reasoning Reasoner |░░░░░░░░░░░░░░░| 0.0% ETA: - Rate: - Time: 0.00s Extracted: -"
+     ]
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Inferred 2 new facts\n",
+      "  Human(Jane)  (rule: Rule 1, confidence: 1.0)\n",
+      "  Human(John)  (rule: Rule 1, confidence: 1.0)\n"
+     ]
+    }
+   ],
+   "source": [
+    "from semantica.reasoning import Reasoner\n",
+    "\n",
+    "reasoner = Reasoner()\n",
+    "\n",
+    "reasoner.add_fact(\"Person(John)\")\n",
+    "reasoner.add_fact(\"Person(Jane)\")\n",
+    "reasoner.add_rule(\"IF Person(?x) THEN Human(?x)\")\n",
+    "\n",
+    "results = reasoner.forward_chain()\n",
+    "print(f\"Inferred {len(results)} new facts\")\n",
+    "for res in results:\n",
+    "    print(f\"  {res.conclusion}  (rule: {res.rule_used.name}, confidence: {res.confidence})\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c1131c45",
+   "metadata": {},
+   "source": [
+    "## 2) One-shot inference with `infer_facts`\n",
+    "\n",
+    "`infer_facts(facts, rules)` **adds** the given facts and rules to this `Reasoner` instance, runs forward chaining to fixpoint, and returns the derived facts as strings. It does not reset the instance's existing state — create a fresh `Reasoner()` first if you need isolation between runs."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "26249990",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:45:59.995447Z",
+     "iopub.status.busy": "2026-08-26T18:45:59.995069Z",
+     "iopub.status.idle": "2026-08-26T18:46:00.004107Z",
+     "shell.execute_reply": "2026-08-26T18:46:00.002873Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "['Employee(Jane, Acme)', 'Employee(John, Acme)']"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from semantica.reasoning import Reasoner\n",
+    "\n",
+    "derived = Reasoner().infer_facts(\n",
+    "    facts=[\"WorksFor(John, Acme)\", \"WorksFor(Jane, Acme)\"],\n",
+    "    rules=[\"IF WorksFor(?x, ?y) THEN Employee(?x, ?y)\"],\n",
+    ")\n",
+    "derived"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d5504a38",
+   "metadata": {},
+   "source": [
+    "## 3) Backward chaining: proving a goal\n",
+    "\n",
+    "`backward_chain(goal)` works backwards from a conclusion through the rules. It returns the `InferenceResult` that proves the goal, or `None`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "c4ef85dd",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:46:00.007740Z",
+     "iopub.status.busy": "2026-08-26T18:46:00.007346Z",
+     "iopub.status.idle": "2026-08-26T18:46:00.015561Z",
+     "shell.execute_reply": "2026-08-26T18:46:00.014145Z"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Human(John)\n",
+      "premises: ['Person(John)']\n"
+     ]
+    }
+   ],
+   "source": [
+    "from semantica.reasoning import Reasoner\n",
+    "\n",
+    "reasoner = Reasoner()\n",
+    "reasoner.add_fact(\"Person(John)\")\n",
+    "reasoner.add_rule(\"IF Person(?x) THEN Human(?x)\")\n",
+    "\n",
+    "proof = reasoner.backward_chain(\"Human(John)\")\n",
+    "print(proof.conclusion if proof else \"not provable\")\n",
+    "print(\"premises:\", proof.premises if proof else None)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b245581d",
+   "metadata": {},
+   "source": [
+    "## 4) Re-run safety\n",
+    "\n",
+    "`add_rule` deduplicates rules with identical conditions and conclusion, so re-executing a setup cell (the common Jupyter re-run) does not duplicate rules — see issue #732."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "fb2aeb39",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:46:00.019091Z",
+     "iopub.status.busy": "2026-08-26T18:46:00.018881Z",
+     "iopub.status.idle": "2026-08-26T18:46:00.024042Z",
+     "shell.execute_reply": "2026-08-26T18:46:00.022836Z"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "Skipping duplicate rule (same conditions/conclusion as 'rule_1'): IF Person(?x) THEN Human(?x)\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "1"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from semantica.reasoning import Reasoner\n",
+    "\n",
+    "reasoner = Reasoner()\n",
+    "reasoner.add_fact(\"Person(John)\")\n",
+    "\n",
+    "# Simulate a Jupyter cell re-run: add the same rule twice\n",
+    "r1 = reasoner.add_rule(\"IF Person(?x) THEN Human(?x)\")\n",
+    "r2 = reasoner.add_rule(\"IF Person(?x) THEN Human(?x)\")\n",
+    "\n",
+    "len(reasoner.rules)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ba2e5c4a",
+   "metadata": {},
+   "source": [
+    "## 5) Datalog reasoning\n",
+    "\n",
+    "`DatalogReasoner` uses classic Datalog syntax (`head :- body.`) and semi-naive fixpoint evaluation. Queries return variable bindings as a list of dicts — use uppercase variables to ask *which* facts hold."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "9ec5c0c4",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:46:00.026769Z",
+     "iopub.status.busy": "2026-08-26T18:46:00.026588Z",
+     "iopub.status.idle": "2026-08-26T18:46:00.034963Z",
+     "shell.execute_reply": "2026-08-26T18:46:00.032672Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[{'X': 'tom', 'Z': 'ann'}]"
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from semantica.reasoning import DatalogReasoner\n",
+    "\n",
+    "datalog = DatalogReasoner()\n",
+    "datalog.add_fact(\"parent(tom, mary)\")\n",
+    "datalog.add_fact(\"parent(mary, ann)\")\n",
+    "datalog.add_rule(\"grandparent(X, Z) :- parent(X, Y), parent(Y, Z)\")\n",
+    "\n",
+    "datalog.derive_all()\n",
+    "datalog.query(\"grandparent(X, Z)\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d4f0689b",
+   "metadata": {},
+   "source": [
+    "## 6) Explanations for inferred conclusions\n",
+    "\n",
+    "`ExplanationGenerator` turns `InferenceResult` objects into structured `Explanation` and `ReasoningPath` records, so agents can show *why* they believe a derived fact."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "19dcd3a7",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:46:00.038649Z",
+     "iopub.status.busy": "2026-08-26T18:46:00.038396Z",
+     "iopub.status.idle": "2026-08-26T18:46:00.059188Z",
+     "shell.execute_reply": "2026-08-26T18:46:00.057805Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "('Explanation', 'ReasoningPath')"
+      ]
+     },
+     "execution_count": 7,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from semantica.reasoning import Reasoner, ExplanationGenerator\n",
+    "\n",
+    "reasoner = Reasoner()\n",
+    "reasoner.add_fact(\"Person(John)\")\n",
+    "reasoner.add_rule(\"IF Person(?x) THEN Human(?x)\")\n",
+    "results = reasoner.forward_chain()\n",
+    "\n",
+    "gen = ExplanationGenerator()\n",
+    "explanation = gen.generate_explanation(results[0])\n",
+    "path = gen.show_reasoning_path(results[0])\n",
+    "\n",
+    "type(explanation).__name__, type(path).__name__"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fb882ee4",
+   "metadata": {},
+   "source": [
+    "## Summary\n",
+    "\n",
+    "| Task | API |\n",
+    "|---|---|\n",
+    "| Derive all new facts | `Reasoner.forward_chain()` |\n",
+    "| One-shot inference | `Reasoner.infer_facts(facts, rules)` |\n",
+    "| Prove a goal | `Reasoner.backward_chain(goal)` |\n",
+    "| Datalog fixpoint | `DatalogReasoner.derive_all()` + `query(\"p(X, Y)\")` |\n",
+    "| Explain a conclusion | `ExplanationGenerator.generate_explanation(result)` |\n",
+    "\n",
+    "See also `semantica/reasoning/reasoning_usage.md` and the module docstrings for `ReteEngine`, `SPARQLReasoner`, and temporal reasoning."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

cookbook/introduction/24_Change_Management.ipynb

@@ -0,0 +1,299 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "8d7096ea",
+   "metadata": {},
+   "source": [
+    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/semantica-agi/semantica/blob/main/cookbook/introduction/24_Change_Management.ipynb)\n",
+    "\n",
+    "# Change Management — Practical Guide\n",
+    "\n",
+    "Semantica's `change_management` module provides versioning, audit trails, and data-integrity checks for knowledge graphs and ontologies:\n",
+    "\n",
+    "- **`ChangeLogEntry`** — standardized change metadata (validated timestamp/author)\n",
+    "- **`InMemoryVersionStorage` / `SQLiteVersionStorage`** — version snapshot storage with named tags\n",
+    "- **`compute_checksum` / `verify_checksum`** — SHA-256 integrity verification\n",
+    "\n",
+    "This notebook runs a complete save → tag → verify → tamper-detect cycle. All outputs are real executed results verified against the repository's `semantica/change_management/` source at the time of writing (the `pip install` cell may fetch a newer release with slightly different behavior)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "7bdffec1",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:46:37.171333Z",
+     "iopub.status.busy": "2026-08-26T18:46:37.171183Z",
+     "iopub.status.idle": "2026-08-26T18:46:39.060860Z",
+     "shell.execute_reply": "2026-08-26T18:46:39.059594Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "!pip install -q semantica"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "169efee1",
+   "metadata": {},
+   "source": [
+    "## 1) A `ChangeLogEntry` records *who* changed *what*, *when*\n",
+    "\n",
+    "`author` must be a valid email — the dataclass validates on construction (`ValidationError` otherwise), which keeps audit trails clean."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "5b17acdb",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:46:39.064077Z",
+     "iopub.status.busy": "2026-08-26T18:46:39.063818Z",
+     "iopub.status.idle": "2026-08-26T18:46:39.321881Z",
+     "shell.execute_reply": "2026-08-26T18:46:39.321036Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "ChangeLogEntry(timestamp='2026-08-15T09:00:00Z', author='demo@example.com', description='initial version', change_id=None, related_changes=[])"
+      ]
+     },
+     "execution_count": 2,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from semantica.change_management import ChangeLogEntry\n",
+    "\n",
+    "entry = ChangeLogEntry(\n",
+    "    timestamp=\"2026-08-15T09:00:00Z\",\n",
+    "    author=\"demo@example.com\",\n",
+    "    description=\"initial version\",\n",
+    ")\n",
+    "entry"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "53d8df5c",
+   "metadata": {},
+   "source": [
+    "## 2) Save a versioned snapshot\n",
+    "\n",
+    "A snapshot is a dict with a required `label` plus your payload. Here we attach the KG data, the change log, and a SHA-256 `checksum` computed over everything except the checksum field itself."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "fec16f24",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:46:39.325528Z",
+     "iopub.status.busy": "2026-08-26T18:46:39.325140Z",
+     "iopub.status.idle": "2026-08-26T18:46:39.331480Z",
+     "shell.execute_reply": "2026-08-26T18:46:39.330586Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "True"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from semantica.change_management import InMemoryVersionStorage, compute_checksum\n",
+    "\n",
+    "storage = InMemoryVersionStorage()\n",
+    "\n",
+    "snapshot = {\n",
+    "    \"label\": \"v1.0.0\",\n",
+    "    \"data\": {\"entities\": {\"acme\": {\"type\": \"Company\"}}},\n",
+    "    \"change_log\": {\n",
+    "        \"timestamp\": entry.timestamp,\n",
+    "        \"author\": entry.author,\n",
+    "        \"description\": entry.description,\n",
+    "    },\n",
+    "}\n",
+    "snapshot[\"checksum\"] = compute_checksum({k: v for k, v in snapshot.items() if k != \"checksum\"})\n",
+    "\n",
+    "storage.save(snapshot)\n",
+    "storage.exists(\"v1.0.0\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0f1c603b",
+   "metadata": {},
+   "source": [
+    "## 3) Named tags pin a version for releases\n",
+    "\n",
+    "`save_tag` / `get_tag` map stable names (e.g. `release`) to version labels, decoupling consumers from label churn."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "62f7643e",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:46:39.335182Z",
+     "iopub.status.busy": "2026-08-26T18:46:39.334886Z",
+     "iopub.status.idle": "2026-08-26T18:46:39.339586Z",
+     "shell.execute_reply": "2026-08-26T18:46:39.338568Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "('v1.0.0', ['v1.0.0'])"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "storage.save_tag(\"release\", \"v1.0.0\")\n",
+    "\n",
+    "storage.get_tag(\"release\"), [s[\"label\"] for s in storage.list_all()]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "96df12da",
+   "metadata": {},
+   "source": [
+    "## 4) Verify integrity — and catch tampering\n",
+    "\n",
+    "`verify_checksum(snapshot)` recomputes the SHA-256 over the snapshot (minus its `checksum` field) and compares. A single mutated character in the data flips the result to `False`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "26d0de85",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:46:39.342653Z",
+     "iopub.status.busy": "2026-08-26T18:46:39.342466Z",
+     "iopub.status.idle": "2026-08-26T18:46:39.346714Z",
+     "shell.execute_reply": "2026-08-26T18:46:39.345623Z"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "intact: True\n",
+      "tampered: False\n"
+     ]
+    }
+   ],
+   "source": [
+    "from semantica.change_management import verify_checksum\n",
+    "\n",
+    "stored = storage.get(\"v1.0.0\")\n",
+    "print(\"intact:\", verify_checksum(stored))\n",
+    "\n",
+    "tampered = storage.get(\"v1.0.0\")\n",
+    "tampered[\"data\"][\"entities\"][\"acme\"][\"note\"] = \"mutated after the fact\"\n",
+    "print(\"tampered:\", verify_checksum(tampered))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bd14c3e4",
+   "metadata": {},
+   "source": [
+    "## 5) Retiring a version\n",
+    "\n",
+    "`delete(label)` removes a snapshot; tags pointing at it are your responsibility to update."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "de9fe3e5",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:46:39.349814Z",
+     "iopub.status.busy": "2026-08-26T18:46:39.349513Z",
+     "iopub.status.idle": "2026-08-26T18:46:39.354710Z",
+     "shell.execute_reply": "2026-08-26T18:46:39.353669Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "False"
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "storage.delete(\"v1.0.0\")\n",
+    "storage.exists(\"v1.0.0\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ab667b32",
+   "metadata": {},
+   "source": [
+    "## Summary\n",
+    "\n",
+    "| Task | API |\n",
+    "|---|---|\n",
+    "| Record audit metadata | `ChangeLogEntry(timestamp, author=email, description)` |\n",
+    "| Persist a version | `InMemoryVersionStorage().save({\"label\": ..., ...})` |\n",
+    "| Pin a release name | `save_tag(\"release\", \"v1.0.0\")` / `get_tag(\"release\")` |\n",
+    "| Integrity check | `compute_checksum(snap)` / `verify_checksum(snap)` |\n",
+    "| Persistent backend | `SQLiteVersionStorage(path)` — same interface |\n",
+    "\n",
+    "See also `semantica/change_management/change_management_usage.md` for the manager classes (`TemporalVersionManager`, `OntologyVersionManager`)."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

cookbook/introduction/25_Seed_Data.ipynb

@@ -0,0 +1,314 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "6eb4dfba",
+   "metadata": {},
+   "source": [
+    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/semantica-agi/semantica/blob/main/cookbook/introduction/25_Seed_Data.ipynb)\n",
+    "\n",
+    "# Seed Data — Practical Guide\n",
+    "\n",
+    "The `seed` module bootstraps a knowledge graph from **trusted, pre-known data** (CSV/JSON/database/API sources) before any extraction runs. This gives extraction a foundation to link against instead of starting from an empty graph.\n",
+    "\n",
+    "Key pieces:\n",
+    "\n",
+    "- **`SeedDataManager`** — registers data sources and builds foundation graphs\n",
+    "- **`create_foundation_graph()`** — turns registered sources into `entities` + `relationships` + `metadata`\n",
+    "- **`validate_quality()`** — checks a foundation graph before you commit it\n",
+    "\n",
+    "All examples below were executed against `semantica/seed/seed_manager.py`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "32f80cc6",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:51:18.716466Z",
+     "iopub.status.busy": "2026-08-26T18:51:18.716264Z",
+     "iopub.status.idle": "2026-08-26T18:51:20.533828Z",
+     "shell.execute_reply": "2026-08-26T18:51:20.531402Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "!pip install -q semantica"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "75136e5f",
+   "metadata": {},
+   "source": [
+    "## 1) Prepare a seed CSV and register the source\n",
+    "\n",
+    "`register_source(name, format, location, entity_type=...)` records where trusted data lives. `verified=True` (the default) marks the source as pre-validated."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "a8089e1f",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:51:20.538772Z",
+     "iopub.status.busy": "2026-08-26T18:51:20.538323Z",
+     "iopub.status.idle": "2026-08-26T18:51:20.675403Z",
+     "shell.execute_reply": "2026-08-26T18:51:20.674060Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "True"
+      ]
+     },
+     "execution_count": 2,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "import csv\n",
+    "import tempfile\n",
+    "from pathlib import Path\n",
+    "from semantica.seed import SeedDataManager\n",
+    "\n",
+    "# Write the sample CSV into a session-scoped temp directory so we never\n",
+    "# clobber a companies.csv that might exist in the user's working directory.\n",
+    "seed_csv = Path(tempfile.mkdtemp(prefix=\"semantica-seed-\")) / \"companies.csv\"\n",
+    "with open(seed_csv, \"w\", newline=\"\") as f:\n",
+    "    writer = csv.DictWriter(f, fieldnames=[\"id\", \"name\", \"type\", \"industry\"])\n",
+    "    writer.writeheader()\n",
+    "    writer.writerow({\"id\": \"c1\", \"name\": \"Acme\", \"type\": \"Company\", \"industry\": \"robotics\"})\n",
+    "    writer.writerow({\"id\": \"c2\", \"name\": \"Globex\", \"type\": \"Company\", \"industry\": \"energy\"})\n",
+    "\n",
+    "manager = SeedDataManager()\n",
+    "manager.register_source(\"companies\", format=\"csv\", location=str(seed_csv), entity_type=\"Company\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e87221ba",
+   "metadata": {},
+   "source": [
+    "## 2) Load records from a registered source\n",
+    "\n",
+    "`load_source(name)` reads the source and enriches each record with `entity_type` and `source` provenance keys."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "f932e550",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:51:20.679424Z",
+     "iopub.status.busy": "2026-08-26T18:51:20.679156Z",
+     "iopub.status.idle": "2026-08-26T18:51:20.690659Z",
+     "shell.execute_reply": "2026-08-26T18:51:20.688812Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "<div style='font-family: monospace;'><h4>🧠 Semantica - 📊 Current Progress</h4><table style='width: 100%; border-collapse: collapse;'><tr><th>Status</th><th>Action</th><th>Module</th><th>Submodule</th><th>Progress</th><th>ETA</th><th>Rate</th><th>Time</th><th>Extracted</th></tr><tr><td>✅</td><td>Semantica is seeding</td><td>🌱 seed</td><td>SeedDataManager</td><td>100.0%</td><td>-</td><td>-</td><td>0.00s</td><td>-</td></tr></table></div>"
+      ],
+      "text/plain": [
+       "<IPython.core.display.HTML object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "🔄 Semantica is seeding: Loading seed data from CSV: /var/folders/7s/bvvstgs10y963tz6_4bbnklr0000gn/T/semantica-seed-eu9__ep1/companies.csv 🌱 seed SeedDataManager |░░░░░░░░░░░░░░░| 0.0% ETA: - Rate: - Time: 0.00s Extracted: -"
+     ]
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "loaded 2 records\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "{'id': 'c1',\n",
+       " 'name': 'Acme',\n",
+       " 'type': 'Company',\n",
+       " 'industry': 'robotics',\n",
+       " 'entity_type': 'Company',\n",
+       " 'source': 'companies'}"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "records = manager.load_source(\"companies\")\n",
+    "print(f\"loaded {len(records)} records\")\n",
+    "records[0]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f2ebce64",
+   "metadata": {},
+   "source": [
+    "## 3) Build the foundation graph\n",
+    "\n",
+    "`create_foundation_graph()` converts every registered source into graph-ready entities and relationships. Entities carry `confidence: 1.0` — seed data is trusted by definition."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "09388c31",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:51:20.695259Z",
+     "iopub.status.busy": "2026-08-26T18:51:20.694928Z",
+     "iopub.status.idle": "2026-08-26T18:51:20.708595Z",
+     "shell.execute_reply": "2026-08-26T18:51:20.707072Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "['entities', 'metadata', 'relationships']"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "foundation = manager.create_foundation_graph()\n",
+    "sorted(foundation.keys())"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "4610a59f",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:51:20.713136Z",
+     "iopub.status.busy": "2026-08-26T18:51:20.712795Z",
+     "iopub.status.idle": "2026-08-26T18:51:20.718637Z",
+     "shell.execute_reply": "2026-08-26T18:51:20.716835Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'id': 'c1',\n",
+       " 'text': 'Acme',\n",
+       " 'type': 'Company',\n",
+       " 'confidence': 1.0,\n",
+       " 'metadata': {'industry': 'robotics', 'source': 'companies'}}"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "foundation[\"entities\"][0]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f3a52dc7",
+   "metadata": {},
+   "source": [
+    "## 4) Validate quality before committing\n",
+    "\n",
+    "`validate_quality(foundation_graph)` returns `valid`, `errors`, `warnings`, and `metrics` so you can gate bad seed data before it pollutes the graph."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "4eb7e664",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-08-26T18:51:20.722674Z",
+     "iopub.status.busy": "2026-08-26T18:51:20.722118Z",
+     "iopub.status.idle": "2026-08-26T18:51:20.732003Z",
+     "shell.execute_reply": "2026-08-26T18:51:20.730170Z"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "True"
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "quality = manager.validate_quality(foundation)\n",
+    "quality[\"valid\"]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b534be89",
+   "metadata": {},
+   "source": [
+    "## Summary\n",
+    "\n",
+    "| Task | API |\n",
+    "|---|---|\n",
+    "| Register a trusted source | `register_source(name, format, location, entity_type=...)` |\n",
+    "| Load records | `load_source(name)` — adds `entity_type` / `source` keys |\n",
+    "| Direct file load | `load_from_csv(path)` / `load_from_json(path)` |\n",
+    "| Build the graph | `create_foundation_graph()` → `entities` / `relationships` / `metadata` |\n",
+    "| Gate bad data | `validate_quality(graph)` → `valid` / `errors` / `warnings` / `metrics` |\n",
+    "\n",
+    "See also `semantica/seed/seed_usage.md` for `load_from_database`, `load_from_api`, and `integrate_with_extracted`."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/cookbook.md

@@ -35,6 +35,7 @@ Essential guides to master the Semantica framework.
 - **[Vector Store](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/13_Vector_Store.ipynb)** — Setting up vector stores for similarity search and retrieval. *Intermediate*
 - **[Graph Store](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/09_Graph_Store.ipynb)** — Persisting knowledge graphs in Neo4j or FalkorDB. Topics: Neo4j, Cypher, Persistence · *Intermediate*
 - **[Ontology](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/14_Ontology.ipynb)** — Defining domain schemas and ontologies to structure your data. Topics: OWL, RDF, Schema Design · *Intermediate*
+- **[Seed Data](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/25_Seed_Data.ipynb)** — Bootstrapping a knowledge graph from trusted CSV, JSON, database, and API sources before extraction runs. Topics: SeedDataManager, Foundation Graphs · *Intermediate*
 
 
 ## Advanced Concepts
@@ -50,6 +51,9 @@ Deep dive into advanced features, customization, and complex workflows.
 - **[Multi-Source Integration](https://github.com/semantica-agi/semantica/blob/main/cookbook/advanced/06_Multi_Source_Data_Integration.ipynb)** — Merging data from disparate sources into a unified graph. Topics: Entity Resolution, Merging, Fusion · *Advanced*
 - **[Reasoning and Inference](https://github.com/semantica-agi/semantica/blob/main/cookbook/advanced/08_Reasoning_and_Inference.ipynb)** — Using logical reasoning to infer new knowledge from existing facts. Topics: Logic Rules, Inference Engines · *Advanced*
 - **[Temporal Knowledge Graphs](https://github.com/semantica-agi/semantica/blob/main/cookbook/advanced/10_Temporal_Knowledge_Graphs.ipynb)** — Modeling and querying data that changes over time. Topics: Time Series, Temporal Logic, Allen Algebra · *Advanced*
+- **[Provenance Tracking](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/22_Provenance_Tracking.ipynb)** — Audit-grade, W3C PROV-O-aligned tracking of where every entity, relationship, and chunk came from. Topics: PROV-O, Lineage, Checksums, Invalidation · *Advanced*
+- **[Reasoning Module](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/23_Reasoning.ipynb)** — Deriving new knowledge from existing facts with forward chaining, backward chaining, and Datalog strategies. Topics: Reasoner, Datalog, Explanations · *Advanced*
+- **[Change Management](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/24_Change_Management.ipynb)** — Versioning, audit trails, and data-integrity checks for knowledge graphs and ontologies. Topics: ChangeLogEntry, Version Storage, Data Integrity · *Advanced*
 
 
 ## How to Run

docs/docs.json

@@ -103,9 +103,11 @@
             "pages": [
               "integrations/agno",
               "integrations/crewai",
+              "integrations/langchain",
               "integrations/docling",
               "integrations/snowflake",
-              "integrations/databricks"
+              "integrations/databricks",
+              "integrations/salesforce"
             ]
           },
           {

docs/faq.md

@@ -17,7 +17,7 @@ icon: "circle-question"
 | API key required? | Optional: pattern extraction works with no keys |
 | Works with LangChain / LlamaIndex? | Yes: Semantica is a layer on top, not a replacement |
 | Production-ready? | Yes: 1,000+ tests, v0.5.0 ships with 12 security fixes |
-| Latest version? | **v0.6.6** (August 2026) |
+| Latest version? | **v0.6.7** (August 2026) |
 | Local LLMs? | Yes: Ollama via LiteLLM, HuggingFaceLLM for air-gapped |
 
 

docs/getting-started.md

@@ -42,7 +42,7 @@ icon: "rocket"
       Verify installation:
       ```python
       import semantica
-      print(semantica.__version__)  # 0.6.6
+      print(semantica.__version__)  # 0.6.7
       ```
     </Check>
   </Step>

docs/guides/ingest.md

@@ -382,6 +382,45 @@ For authentication details (PAT vs. OAuth M2M for Databricks; password vs. key-p
 
 > **Security Note:** Never hardcode credentials (`token`, `password`, `private_key`) in production code; pass them via environment variables (e.g., `DATABRICKS_TOKEN`, `SNOWFLAKE_PASSWORD`) or a secrets manager.
 
+## Source 7 — SAP OData
+
+`SAPIngestor` ingests an Entity Set from a SAP OData service (S/4HANA Cloud, SuccessFactors, or an on-prem NetWeaver Gateway over its REST surface). It speaks OData v2 and v4, follows server-driven pagination automatically, and flattens each record into a document dict via `export_as_documents()` — the same structured "transform to text, then store" pattern as the other sources.
+
+```python
+from semantica.ingest import SAPIngestor
+
+ing = SAPIngestor(
+    base_url="https://my-sap.example.com/sap/opu/odata/sap/API_BUSINESS_PARTNER",
+    client_id="...", client_secret="...",
+    token_url="https://my-sap.example.com/oauth/token",  # OAuth2 client-credentials (BTP/S/4HANA Cloud)
+    # On-prem NetWeaver often uses Basic auth instead — swap the block above for:
+    # username="erp_user", password="...",
+)
+
+# 1. Discover an unfamiliar service: entity sets + field types from $metadata
+sets = ing.discover_service()          # [{"name": "A_BusinessPartnerSet", "fields": [...]}, ...]
+
+# 2. Pull a page-walked Entity Set (v2/v4 next links handled for you)
+partners = ing.ingest_entity_set(
+    entity_set="A_BusinessPartnerSet",
+    select="BusinessPartner,BusinessPartnerFullName",   # $select
+    top=1000,                                           # cap on total rows
+)
+
+# 3. Flatten to document dicts, then build text for the graph
+docs = ing.export_as_documents(partners)
+partner_texts = [
+    f"Business Partner {d['BusinessPartner']}: {d['BusinessPartnerFullName']}"
+    for d in docs
+]
+```
+
+- Use `expand="to_Item"` (e.g. on a sales-order header set) to pull nested line items in one request — handy for modeling order → line-item → material relationships.
+- Every outbound request, including the OAuth2 token exchange, is routed through the SSRF guard, so a user-supplied SAP URL can never reach private/loopback/link-local address space.
+- Install with `pip install 'semantica[ingest-sap]'`.
+
+> **Security Note:** Never hardcode credentials (`client_secret`, `password`) in code; pass them via environment variables (e.g., `SAP_CLIENT_SECRET`, `SAP_PASSWORD`) or a secrets manager.
+
 ## Combining All Five Sources
 
 Once you have text from each source, `AgentContext.store()` accepts a flat list of strings. Semantica embeds and indexes them together — the context graph has no concept of which string came from which source unless you add metadata explicitly.

docs/guides/llm-integrations.md

@@ -28,6 +28,7 @@ The `semantica.llms` module provides a unified interface for connecting to Large
 ## When To Use / When Not To Use
 
 **Use LLM integrations for:**
+
 - Text generation, summarization, and question-answering tasks
 - Complex reasoning that requires natural language understanding
 - Structured data extraction from unstructured text
@@ -35,6 +36,7 @@ The `semantica.llms` module provides a unified interface for connecting to Large
 - Tasks where context, ambiguity, or domain knowledge matter
 
 **Deterministic tools may be better for:**
+
 - Pattern matching that regular expressions can handle
 - Simple rule-based classification with clear criteria
 - Mathematical calculations or statistical analysis
@@ -42,6 +44,7 @@ The `semantica.llms` module provides a unified interface for connecting to Large
 - Data transformations with known logic
 
 **A full LLM may be unnecessary for:**
+
 - Simple keyword search or exact string matching
 - Deterministic workflows with predefined decision trees
 - High-frequency, low-latency operations where inference overhead matters
@@ -59,7 +62,7 @@ Four factors drive provider selection, each optimized for different use cases:
 
 **Accuracy** matters most in high-stakes decisions: clinical contraindication checks, credit committee reasoning, and legal document analysis. Frontier models like Claude or GPT-4 available through `LiteLLM` provide the strongest reasoning capabilities.
 
-**Data residency** constraints eliminate cloud providers for classified or HIPAA-regulated workloads. `HuggingFaceLLM` with local model paths enables fully air-gapped deployments without network calls.
+**Data residency** constraints eliminate cloud providers for classified or HIPAA-regulated workloads. `HuggingFaceLLM` with local model paths, or `Ollama` pointed at a local server, both enable fully air-gapped deployments without network calls.
 
 **Cost at scale** favors high-throughput providers like Novita AI for bulk extraction pipelines processing thousands of documents per hour where per-token costs accumulate quickly.
 
@@ -143,6 +146,131 @@ risk_data = oai.generate_structured(
 
 The default model `gpt-3.5-turbo` is fine for classification and light extraction. Switch to `gpt-4o` for complex multi-step regulatory reasoning or document understanding.
 
+## Anthropic — Complex Reasoning and Structured Extraction
+
+**Anthropic** provides the Claude model family, built with an emphasis on careful, instruction-following behavior and strong performance on multi-step reasoning, long-document analysis, and code-related tasks. Claude models tend to be more cautious about ambiguous instructions than other providers. That matters when the cost of a confidently wrong answer is high.
+
+The `Anthropic` provider wraps the Claude API. Reach for it when the task involves reasoning through several dependent steps (not just single-turn extraction), when you're processing long source documents that need to stay in context, or when you need schema-validated structured output rather than best-effort JSON.
+
+Install with `pip install "semantica[llm-anthropic]"` (or just `pip install anthropic`) before using this provider.
+
+```python
+from semantica.llms import Anthropic
+
+claude = Anthropic(model="claude-sonnet-4-6", api_key="YOUR_ANTHROPIC_KEY")
+# api_key falls back to the ANTHROPIC_API_KEY environment variable
+
+# is_available() only confirms a client was constructed from some key.
+# It does not validate the key or check network reachability - an
+# invalid or expired key still passes this check and fails at generate().
+if not claude.is_available():
+    raise RuntimeError("Anthropic provider not configured - set ANTHROPIC_API_KEY")
+
+# Plain generation - multi-step reasoning over a contract clause
+verdict = claude.generate(
+    "A vendor contract has a 30-day termination-for-convenience clause "
+    "but a 90-day data-return obligation that survives termination. "
+    "If the customer terminates on day 1, when must vendor-held data "
+    "be returned? Answer with the date basis only.",
+    temperature=0.1,
+)
+print(verdict)
+# "Day 120 from termination notice. The 90-day return period runs from
+#  the termination date (day 30), not from the notice date."
+
+# Structured, schema-validated output
+from pydantic import BaseModel
+
+class ContractRisk(BaseModel):
+    clause: str
+    risk_level: str
+    days_to_deadline: int
+
+risk = claude.generate_typed(
+    "Extract the termination clause risk from: vendor contract, "
+    "30-day termination for convenience, 90-day post-termination "
+    "data return obligation.",
+    schema=ContractRisk,
+)
+print(risk.risk_level, risk.days_to_deadline)
+# "medium" 90
+```
+
+Model selection follows the same tier structure as the other providers: a Haiku model for high-volume classification where cost matters more than depth, a Sonnet model as the default for most extraction and reasoning tasks, an Opus model when a task genuinely needs the deepest reasoning available and latency/cost are secondary. Check Anthropic's docs for the current model identifiers, since they're versioned and change over time.
+
+## Gemini — Long Context and Multimodal Input
+
+**Gemini** is Google's model family, with a context window large enough to hold entire codebases or long regulatory filings in a single call, and native support for image and document input alongside text. Reach for it when a task needs to reference a large amount of source material at once, or when the input isn't plain text.
+
+The `Gemini` provider tries the newer `google-genai` SDK first and falls back to the older `google-generativeai` package if that's what's installed. Install with `pip install "semantica[llm-gemini]"` (or `pip install google-genai`) before using this provider.
+
+```python
+from semantica.llms import Gemini
+
+gemini = Gemini(model="gemini-pro", api_key="YOUR_GEMINI_KEY")
+# api_key falls back to the GEMINI_API_KEY environment variable
+
+if not gemini.is_available():
+    raise RuntimeError("Gemini provider not configured - set GEMINI_API_KEY")
+
+response = gemini.generate(
+    "Summarize the key obligations in a standard NDA in three bullet points."
+)
+print(response)
+
+data = gemini.generate_structured(
+    "Extract the party names and effective date from: "
+    "This Agreement is entered into between Acme Corp and Globex LLC, "
+    "effective January 1, 2026."
+)
+print(data)
+```
+
+## Ollama — Local, Air-Gapped Inference
+
+**Ollama** runs models entirely on your own machine, with no API key and no outbound network call. It's the right choice for air-gapped environments, offline development, or any workload where the source data can't leave the local network.
+
+Unlike the other providers here, `Ollama` takes a `base_url` instead of an `api_key`. It talks to a local Ollama server over HTTP. Start the server with `ollama serve` and pull a model with `ollama pull llama2` before using this provider. Install the Python client with `pip install "semantica[llm-ollama]"` (or `pip install ollama`).
+
+```python
+from semantica.llms import Ollama
+
+llm = Ollama(model="llama2", base_url="http://localhost:11434")
+
+if not llm.is_available():
+    raise RuntimeError("Ollama provider not configured - is 'ollama serve' running?")
+
+response = llm.generate("Explain the difference between a hash map and a tree map.")
+print(response)
+```
+
+`is_available()` for Ollama does a real connectivity check (it calls the server's `list()` endpoint), unlike the API-key-based providers above, so a `False` here usually means the server isn't running rather than a missing credential.
+
+## DeepSeek — Budget Reasoning at Scale
+
+**DeepSeek** exposes an OpenAI-compatible API at a fraction of the cost of the larger US providers, with reasoning quality that holds up well for extraction and classification work. It's a reasonable default when you're processing a large volume of documents and don't need the deepest reasoning tier.
+
+Install with `pip install "semantica[llm-deepseek]"` (or `pip install openai`, since DeepSeek is accessed through the OpenAI client pointed at a different base URL).
+
+```python
+from semantica.llms import DeepSeek
+
+llm = DeepSeek(model="deepseek-chat", api_key="YOUR_DEEPSEEK_KEY")
+# api_key falls back to the DEEPSEEK_API_KEY environment variable
+
+if not llm.is_available():
+    raise RuntimeError("DeepSeek provider not configured - set DEEPSEEK_API_KEY")
+
+response = llm.generate("List three risks of using a floating IP in a Kubernetes ingress.")
+print(response)
+
+data = llm.generate_structured(
+    "Extract the CVE ID and affected product from: "
+    "CVE-2024-3400 affects PAN-OS GlobalProtect gateways."
+)
+print(data)
+```
+
 ## LiteLLM — One Interface, 100+ Providers
 
 **LiteLLM** is a universal adapter that provides a single interface to over 100 different LLM providers, including Anthropic Claude, Azure OpenAI, AWS Bedrock, Google Vertex AI, and local Ollama instances. It acts as a translation layer, converting your unified API calls into provider-specific requests, enabling easy switching between providers without code changes.
@@ -306,30 +434,32 @@ for t in triplets:
 
 ## Novita AI — Cost-Efficient Bulk Extraction
 
-Novita AI exposes an OpenAI-compatible API and is available as a built-in provider for the extraction layer. It is accessed differently from the `semantica.llms` classes — through `create_provider` from `semantica.semantic_extract.providers` — making it the right choice for high-volume NER pipelines where per-call cost matters.
+**Novita AI** exposes an OpenAI-compatible API at low per-call cost, making it a reasonable choice for high-volume NER pipelines where cost matters more than getting the single best answer.
+
+Install with `pip install "semantica[llm-novita]"` (or `pip install openai`, since Novita is accessed through the OpenAI client pointed at a different base URL).
+
+```python
+from semantica.llms import Novita
+
+llm = Novita(model="deepseek/deepseek-v3.2", api_key="YOUR_NOVITA_KEY")
+# api_key falls back to the NOVITA_API_KEY environment variable
+
+if not llm.is_available():
+    raise RuntimeError("Novita provider not configured - set NOVITA_API_KEY")
+
+response = llm.generate("Summarize the Basel III leverage ratio requirement.")
+
+data = llm.generate_structured(
+    "Extract drug names and dosages from: "
+    "Patient received warfarin 5mg daily, aspirin 75mg daily, metformin 500mg twice daily."
+)
+```
+
+Novita is also reachable as a provider name string for the NER interface, without going through the `Novita` class directly:
 
 ```python
-from semantica.semantic_extract.providers import create_provider
 from semantica.semantic_extract import NamedEntityRecognizer
 
-# create_provider pools instances — same key reuses the same object
-provider = create_provider(
-    "novita",
-    api_key="YOUR_NOVITA_KEY",       # or set NOVITA_API_KEY env var
-    model="deepseek/deepseek-v3.2",  # default model
-)
-
-if provider.is_available():
-    # Plain generation
-    response = provider.generate("Summarise the Basel III leverage ratio requirement.")
-
-    # Structured extraction — returns parsed dict
-    data = provider.generate_structured(
-        "Extract drug names and dosages from: "
-        "Patient received warfarin 5mg daily, aspirin 75mg daily, metformin 500mg twice daily."
-    )
-
-# Use Novita through the NER interface — provider name as string
 ner = NamedEntityRecognizer(
     methods=["llm"],
     provider="novita",
@@ -339,11 +469,9 @@ entities = ner.extract_entities(
     "CVE-2024-3400 is exploited by UNC3886 targeting PAN-OS GlobalProtect."
 )
 for e in entities:
-    print("{} ({}) — conf={:.2f}".format(e.text, e.label, e.confidence))
+    print("{} ({}) conf={:.2f}".format(e.text, e.label, e.confidence))
 ```
 
-Novita requires the `openai` Python client under the hood — install with `pip install "semantica[llm-openai]"` or `pip install openai`.
-
 ## Domain Examples
 
 <Tabs>

docs/guides/pipeline.md

@@ -222,10 +222,10 @@ builder.register_step_handler("ner_extract",     run_ner)
 builder.register_step_handler("triplet_extract", run_triplets)
 builder.register_step_handler("kg_merge",        merge_into_graph)
 
-builder.add_step("ingest",   "file_ingest",     handler=ingest_stix_bundles, path="./stix_bundles/")
-builder.add_step("ner",      "ner_extract",     handler=run_ner,             confidence_threshold=0.75)
-builder.add_step("triplets", "triplet_extract", handler=run_triplets,        include_temporal=True)
-builder.add_step("store",    "kg_merge",        handler=merge_into_graph,    output_path="./cti_output/")
+builder.add_step("ingest",   "file_ingest",     path="./stix_bundles/")
+builder.add_step("ner",      "ner_extract",     confidence_threshold=0.75)
+builder.add_step("triplets", "triplet_extract", include_temporal=True)
+builder.add_step("store",    "kg_merge",        output_path="./cti_output/")
 
 # ingest feeds both ner and triplets in parallel
 builder.connect_steps("ingest",   "ner")
@@ -241,7 +241,18 @@ engine   = ExecutionEngine(max_workers=2, retry_on_failure=True)
 result   = engine.execute_pipeline(pipeline)
 ```
 
-`set_parallelism(n)` tells the engine how many steps it may run simultaneously. The topological sort guarantees that only steps whose dependencies are all completed are eligible for concurrent execution — you cannot accidentally run a step before its inputs are ready.
+`set_parallelism(n)` tells the engine how many steps it may run simultaneously; `n` must be a positive integer. The topological sort guarantees that only steps whose dependencies are all completed are eligible for concurrent execution — you cannot accidentally run a step before its inputs are ready. The effective concurrency is capped at `min(n, max_workers)`, so the engine's `max_workers` setting remains a hard resource ceiling.
+
+Concurrency is opt-in per step. A dependency layer only runs in parallel when every step in that layer is marked `parallel_safe`, the layer has more than one step, and the data flowing into the layer is a dict:
+
+```python
+builder.add_step("ner",      "ner_extract",     parallel_safe=True, confidence_threshold=0.75)
+builder.add_step("triplets", "triplet_extract", parallel_safe=True, include_temporal=True)
+```
+
+If any step in a layer is not marked `parallel_safe`, or if a step runs in delta mode, the entire layer falls back to sequential execution — parallelism never silently bypasses a step that was not declared safe. `parallel_safe` is a control field: like `dependencies`, it is consumed by the builder and never reaches your handler's config.
+
+Parallel-safe handlers must return a dict. Each step in a parallel layer receives an isolated deep copy of the layer's input, so steps cannot see each other's mutations. The per-step results are merged key by key in step declaration order: a key written by one step is added to the merged output, a key written by several steps with equal values is kept, and two steps writing different values for the same key fail the pipeline with a `ProcessingError` naming the conflicting key and both steps. Handlers that touch shared mutable resources — database connections, in-memory stores, global caches — should not be marked `parallel_safe`.
 
 ## Common Pitfalls
 

docs/guides/provenance.md

@@ -639,7 +639,7 @@ Every `ProvenanceEntry` maps directly to W3C PROV-O terms. If your compliance te
 | — | `previous_version_id` | This entry corrects/replaces a prior version of the *same* fact |
 | `prov:wasDerivedFrom` | `derived_from_id` | This entry was derived from a *different* source entity |
 | `prov:used` | `used_entities` | Entity IDs consumed to produce this one |
-| `prov:generatedAtTime` | `timestamp` | ISO datetime, auto-set to `datetime.utcnow()` at write time |
+| `prov:generatedAtTime` | `timestamp` | ISO datetime, auto-set to `utc_now_iso()` at write time |
 | `prov:qualifiedInvalidation` | `invalidated`, `invalidated_at_time`, `invalidated_by`, `invalidation_reason` | A retraction/correction recorded as a tombstone via `ProvenanceManager.invalidate()`, never a hard delete |
 | `prov:startedAtTime` / `prov:endedAtTime` | `activity_started_at_time`, `activity_ended_at_time` | Typed Activity timing — pass an `ActivityRecord` via the `activity=` kwarg to set these together with `activity_id` |
 | `prov:qualifiedGeneration`/`Generation`, `qualifiedUsage`/`Usage`, `qualifiedDerivation`/`Derivation` | (derived from the fields above) | Additive qualified forms of `wasGeneratedBy`/`used`/`wasDerivedFrom`, emitted automatically alongside the plain triples |

docs/guides/reasoning.md

@@ -150,6 +150,12 @@ HighRiskSupplier(DELTA-3)                 conf=100%  rule=Rule 3
 
 DELTA-3 is flagged even though no document described it that way — the system traced: DELTA-3 supplied GAMMA-7, and GAMMA-7 exploits critical CVEs. For rules that need priority ordering or graded confidence, use the `Rule` dataclass:
 
+If a rule has side-effecting actions, one concrete activation runs those
+actions at most once on a Reasoner instance. Re-running `forward_chain()` is
+therefore safe: already-attempted actions are not repeated. Use
+`reasoner.reset_action_history()` when you intentionally want to replay them;
+`reasoner.clear()` and `reasoner.reset()` also clear the history.
+
 ```python
 # Higher priority rules fire first; confidence propagates into InferenceResult.confidence
 reasoner.add_rule(Rule(
@@ -360,6 +366,13 @@ engine.reset()
 
 The rule network is compiled once by `build_network()`. Each subsequent `add_fact()` call propagates incrementally through only the nodes whose conditions it satisfies — not the full rule set — which keeps evaluation cost proportional to the number of new activations rather than the total rule count.
 
+With a Reasoner bound, Rete action side effects are attempted once per rule,
+bindings, and matched fact identity. Passing the same match to
+`execute_matches()` again still returns the same conclusion, but does not repeat
+its actions. Call `engine.reset_action_history()` to replay actions without
+clearing working memory. `engine.reset()` and `engine.build_network()` also
+clear the action history.
+
 ## Step 7 — Temporal interval reasoning
 
 `TemporalReasoningEngine` computes Allen interval relations between time windows, letting you identify whether two events overlap, one contains the other, they meet at a boundary, and so on across your graph:

docs/integrations/langchain.md

@@ -0,0 +1,81 @@
+---
+title: "LangChain Integration"
+description: "Drop Semantica into LangChain / LangGraph pipelines via a GraphRAG retriever, VectorStore adapter, and agent tools."
+icon: "link"
+---
+
+> Three drop-in adapters that bring Semantica's context graph and hybrid search into LangChain chains and LangGraph agents.
+
+## Installation
+
+```bash
+pip install "semantica[langchain]"
+```
+
+Requires `langchain-core >= 0.3`. If langchain-core is not installed, the integration still imports — every class carries the full Semantica API and degrades gracefully (`build()` returns `None`; branch on `LANGCHAIN_AVAILABLE`).
+
+## Components at a Glance
+
+- **SemanticaRetriever** — `BaseRetriever`: hybrid-search seeds retrieval, then graph edges are walked `hops` steps (default 2) for GraphRAG-style results.
+- **SemanticaVectorStore** — `VectorStore`: `add_texts` / `similarity_search` / `similarity_search_with_score` / `from_texts` over `HybridSearch`.
+- **SemanticaKGTool** / **SemanticaDecisionTool** — `BaseTool` subclasses: `semantica_query_graph` and `semantica_query_decisions` for LangGraph / tool-calling agents.
+
+## Component Details
+
+<Tabs>
+  <Tab title="SemanticaRetriever">
+    Hybrid search seeds retrieval; then graph edges are walked `hops` steps so results go beyond flat vector similarity. If hybrid search is omitted or fails, the retriever falls back to a `ContextGraph.query` keyword scan.
+
+    ```python
+    from integrations.langchain import SemanticaRetriever
+    from semantica.context import ContextGraph
+    from semantica.vector_store import HybridSearch
+
+    graph = ContextGraph()
+    hybrid = HybridSearch()
+
+    retriever = SemanticaRetriever(graph=graph, hybrid=hybrid, hops=2, top_k=10)
+
+    from langchain.chains import RetrievalQA
+
+    qa = RetrievalQA.from_chain_type(llm=llm, retriever=retriever)
+    ```
+  </Tab>
+  <Tab title="SemanticaVectorStore">
+    Drop-in `VectorStore` for RetrievalQA / LCEL chains. `from_texts` requires a pre-configured `hybrid` instance.
+
+    ```python
+    from integrations.langchain import SemanticaVectorStore
+
+    store = SemanticaVectorStore(hybrid=hybrid)
+    store.add_texts(
+        ["document one", "document two"],
+        metadatas=[{"source": "a"}, {"source": "b"}],
+    )
+    docs = store.similarity_search("document", k=2)
+    docs, scores = store.similarity_search_with_score("document", k=2)
+    ```
+
+    `add_texts` delegates to a Semantica vector store with `add_documents` (pass `vector_store=` to `HybridSearch` or to `SemanticaVectorStore`).
+  </Tab>
+  <Tab title="Agent tools">
+    Instances are LangChain `BaseTool`s and can be passed to an agent directly.
+    `.build()` returns the tool, or `None` when langchain-core is absent.
+
+    ```python
+    from integrations.langchain import SemanticaKGTool, SemanticaDecisionTool
+    from langgraph.prebuilt import create_react_agent
+
+    tools = [
+        SemanticaKGTool(graph),
+        SemanticaDecisionTool(graph),
+    ]
+    agent = create_react_agent(model, tools)
+    ```
+
+    | Tool | Description |
+    | :------ | :------------- |
+    | `semantica_query_graph` | Keyword / NL query over the shared context graph |
+    | `semantica_query_decisions` | Search the recorded decision log |
+  </Tab>
+</Tabs>

docs/integrations/salesforce.md

@@ -0,0 +1,376 @@
+---
+title: "Salesforce Integration"
+description: "Ingest CRM records from Salesforce sObjects and SOQL queries into Semantica's KG pipeline."
+icon: "cloud"
+---
+
+> Extract Accounts, Contacts, Opportunities, and custom objects from Salesforce into Semantica with username/password/security-token, JWT bearer, or session-based authentication.
+
+
+## Installation
+
+```bash
+# Install with Salesforce support
+pip install "semantica[db-salesforce]"
+
+# Or install the connector separately
+pip install simple-salesforce>=1.12.0
+```
+
+
+## Basic Usage
+
+```python
+from semantica.ingest import SalesforceIngestor
+import os
+
+ingestor = SalesforceIngestor(
+    username=os.getenv("SALESFORCE_USERNAME"),
+    password=os.getenv("SALESFORCE_PASSWORD"),
+    security_token=os.getenv("SALESFORCE_SECURITY_TOKEN"),
+    domain=os.getenv("SALESFORCE_DOMAIN", "login"),   # "test" for sandbox
+)
+
+data = ingestor.ingest_sobject("Account", fields=["Id", "Name", "Industry"], limit=1000)
+print(f"Retrieved {data.row_count} of {data.total_size} matching records")
+print(f"Columns: {data.columns}")
+```
+
+<Tip>
+Use environment variables (or a `.env` file with `python-dotenv`) to keep credentials out of source code. `SalesforceIngestor()` with no arguments reads from `SALESFORCE_*` environment variables automatically.
+</Tip>
+
+
+## Authentication Methods
+
+<Tabs>
+  <Tab title="Username / Password / Security Token">
+    ```python
+    import os
+    from semantica.ingest import SalesforceIngestor
+
+    ingestor = SalesforceIngestor(
+        username=os.getenv("SALESFORCE_USERNAME"),
+        password=os.getenv("SALESFORCE_PASSWORD"),
+        security_token=os.getenv("SALESFORCE_SECURITY_TOKEN"),
+        domain="login",   # production; use "test" for sandbox
+    )
+    ```
+    Set the required environment variables before running:
+    ```bash
+    export SALESFORCE_USERNAME="your-username@example.com"
+    export SALESFORCE_PASSWORD="your-password"
+    export SALESFORCE_SECURITY_TOKEN="your-security-token"
+    ```
+    The standard server-side flow. The security token is appended to the
+    password during Salesforce SOAP login. Generate or reset it under
+    **Settings → My Personal Information → Reset My Security Token**.
+  </Tab>
+  <Tab title="JWT Bearer (Recommended for CI/CD)">
+    ```python
+    import os
+    from semantica.ingest import SalesforceIngestor
+
+    ingestor = SalesforceIngestor(
+        username=os.getenv("SALESFORCE_USERNAME"),
+        consumer_key=os.getenv("SALESFORCE_CONSUMER_KEY"),
+        privatekey_file=os.getenv("SALESFORCE_PRIVATE_KEY_FILE"),
+        domain="login",   # or "test" for sandbox
+    )
+    ```
+    ```bash
+    export SALESFORCE_USERNAME="your-username@example.com"
+    export SALESFORCE_CONSUMER_KEY="your-connected-app-consumer-key"
+    export SALESFORCE_PRIVATE_KEY_FILE="/path/to/server.key"
+    ```
+    The JWT bearer flow authenticates with a signed token — no password
+    is transmitted. Ideal for server-to-server integrations and CI/CD
+    pipelines. Requires a Salesforce connected app configured with
+    **Use digital signatures** and the pre-authorised user listed under
+    **Manage → Profiles / Permission Sets**.
+
+    If you prefer to pass the key material as a string instead of a file
+    path, use `SALESFORCE_PRIVATE_KEY` (the PEM contents) in place of
+    `SALESFORCE_PRIVATE_KEY_FILE`.
+  </Tab>
+  <Tab title="Session ID + Instance URL">
+    ```python
+    ingestor = SalesforceIngestor(
+        session_id=os.getenv("SALESFORCE_SESSION_ID"),
+        instance_url=os.getenv("SALESFORCE_INSTANCE_URL"),
+    )
+    ```
+    Use this when your environment already manages the OAuth token
+    lifecycle (e.g. a connected app obtaining tokens via the web-server
+    or device flow). Pass the access token as `session_id` and the full
+    instance URL (e.g. `https://myorg.my.salesforce.com`) as
+    `instance_url`.
+  </Tab>
+  <Tab title="Sandbox">
+    ```python
+    import os
+    from semantica.ingest import SalesforceIngestor
+
+    ingestor = SalesforceIngestor(
+        username=os.getenv("SALESFORCE_USERNAME"),
+        password=os.getenv("SALESFORCE_PASSWORD"),
+        security_token=os.getenv("SALESFORCE_SECURITY_TOKEN"),
+        domain="test",   # routes to test.salesforce.com
+    )
+    ```
+    ```bash
+    export SALESFORCE_USERNAME="your-sandbox-username@example.com.sandbox"
+    export SALESFORCE_PASSWORD="your-password"
+    export SALESFORCE_SECURITY_TOKEN="your-security-token"
+    export SALESFORCE_DOMAIN="test"
+    ```
+    Replace `domain="login"` with `domain="test"` (or set
+    `SALESFORCE_DOMAIN=test` in your environment) to connect to a
+    developer or full sandbox.
+  </Tab>
+</Tabs>
+
+### Environment variables
+
+All constructor parameters have environment-variable fallbacks:
+
+| Variable | Parameter | Default |
+|---|---|---|
+| `SALESFORCE_USERNAME` | `username` | — |
+| `SALESFORCE_PASSWORD` | `password` | — |
+| `SALESFORCE_SECURITY_TOKEN` | `security_token` | — |
+| `SALESFORCE_DOMAIN` | `domain` | `"login"` |
+| `SALESFORCE_INSTANCE_URL` | `instance_url` | — |
+| `SALESFORCE_SESSION_ID` | `session_id` | — |
+| `SALESFORCE_CONSUMER_KEY` | `consumer_key` | — |
+| `SALESFORCE_PRIVATE_KEY_FILE` | `privatekey_file` | — |
+| `SALESFORCE_PRIVATE_KEY` | `privatekey` | — |
+| `SALESFORCE_API_VERSION` | `api_version` | library default (`59.0`) |
+
+
+## Object Ingestion
+
+### Ingest a standard object
+
+```python
+data = ingestor.ingest_sobject(
+    "Account",
+    fields=["Id", "Name", "Industry", "AnnualRevenue", "BillingCity"],
+    where="Type = 'Customer' AND AnnualRevenue > 1000000",
+    order_by="Name ASC",
+    limit=5000,
+)
+print(f"Retrieved {data.row_count} of {data.total_size} matching records")
+```
+
+<Note>
+`data.row_count` is the number of records in `data.data` (i.e. what was actually returned after any `limit`). `data.total_size` is Salesforce's `totalSize` — the number of records matching the query *before* the limit. Compare them to know whether you got all results.
+</Note>
+
+### Ingest a custom object
+
+Custom objects end with `__c` in their API name:
+
+```python
+data = ingestor.ingest_sobject(
+    "My_Custom_Object__c",
+    fields=["Id", "Name", "Custom_Field__c"],
+)
+```
+
+Relationship traversal fields (`Owner.Name`) are also supported:
+
+```python
+data = ingestor.ingest_sobject(
+    "Contact",
+    fields=["Id", "Name", "Email", "Account.Name", "Owner.Name"],
+    limit=10000,
+)
+```
+
+### Let Semantica choose the fields
+
+When `fields` is omitted, all selectable fields are fetched via `describe()`
+(one extra API call). Compound address and geolocation fields (`type=address`,
+`type=location`) are automatically excluded — select their components
+(`BillingStreet`, `BillingCity`, `Location__Latitude__s`, …) individually if
+you need them.
+
+```python
+data = ingestor.ingest_sobject("Opportunity")
+```
+
+
+## Raw SOQL Ingestion
+
+Pass any valid SOQL query verbatim — pagination is handled automatically:
+
+```python
+data = ingestor.ingest_query("""
+    SELECT Id, Name, StageName, Amount, CloseDate,
+           Account.Name, Owner.Name
+    FROM Opportunity
+    WHERE IsClosed = false
+    ORDER BY CloseDate ASC
+""")
+print(f"Open opportunities: {data.row_count}")
+```
+
+The query is passed to the Salesforce REST API unchanged. The caller is
+responsible for SOQL correctness and safety.
+
+<Warning>
+`ingest_query` does not validate or sanitise the SOQL string. Use
+`ingest_sobject` (which validates sObject names, field names, and WHERE/ORDER
+BY fragments) when building queries from application-controlled inputs.
+</Warning>
+
+
+## Document Export
+
+Convert ingested records to the Semantica document format for use with
+`GraphBuilder`:
+
+```python
+documents = ingestor.export_as_documents(
+    data,
+    id_field="Id",                            # default; Salesforce 18-char record Id
+    text_fields=["Name", "Description"],      # omit to join all string fields
+)
+
+print(f"Created {len(documents)} documents")
+# Each document:
+# {
+#   "id": "001xx000003GYk2AAG",
+#   "text": "Acme Corp Enterprise software company",
+#   "metadata": {
+#     "source": "salesforce",
+#     "sobject": "Account",
+#     "instance_url": "https://myorg.my.salesforce.com",
+#     "row_data": { ... full cleaned record ... }
+#   }
+# }
+```
+
+Feed the documents directly into `GraphBuilder`:
+
+```python
+from semantica.kg import GraphBuilder
+
+builder = GraphBuilder()
+kg = builder.build(documents)
+```
+
+
+## Object and Schema Discovery
+
+```python
+# List all accessible sObjects
+sobject_names = ingestor.list_sobjects()
+print(sobject_names[:10])   # ["Account", "Case", "Contact", ...]
+
+# Inspect fields for a specific sObject
+schema = ingestor.get_sobject_schema("Account")
+for field in schema["fields"]:
+    print(f"{field['name']}: {field['type']} (nillable={field['nillable']})")
+```
+
+
+## Context Manager
+
+Prefer the context manager for long-running jobs — it opens one connection on
+entry and closes it on exit, so every ingestion call inside the `with` block
+reuses the same authenticated session:
+
+```python
+with SalesforceIngestor(
+    username=os.getenv("SALESFORCE_USERNAME"),
+    password=os.getenv("SALESFORCE_PASSWORD"),
+    security_token=os.getenv("SALESFORCE_SECURITY_TOKEN"),
+) as sf:
+    accounts = sf.ingest_sobject("Account", limit=10000)
+    contacts = sf.ingest_sobject("Contact", limit=10000)
+    sobjects = sf.list_sobjects()
+```
+
+
+## Convenience Function
+
+Use `ingest_salesforce()` for one-liner ingestion:
+
+```python
+from semantica.ingest import ingest_salesforce
+
+# Fetch records
+data = ingest_salesforce(
+    method="sobject",
+    sobject_name="Account",
+    fields=["Id", "Name", "Industry"],
+    limit=500,
+)
+
+# Execute raw SOQL (credentials from environment variables)
+data = ingest_salesforce(
+    method="query",
+    soql="SELECT Id, Name FROM Contact WHERE IsActive = true",
+)
+
+# Ingest + export to documents in one step
+docs = ingest_salesforce(
+    method="documents",
+    sobject_name="Account",
+    text_fields=["Name", "Description"],
+    limit=1000,
+)
+
+# List accessible sObjects
+sobject_names = ingest_salesforce(method="list_sobjects")
+```
+
+Or use the unified `ingest()` dispatcher:
+
+```python
+from semantica.ingest import ingest
+
+result = ingest(
+    None,
+    source_type="salesforce",
+    method="sobject",
+    sobject_name="Account",
+    fields=["Id", "Name"],
+    limit=500,
+)
+data = result["data"]   # SalesforceData
+```
+
+
+## Troubleshooting
+
+```python
+import os
+from semantica.ingest import SalesforceConnector
+
+connector = SalesforceConnector(
+    username=os.getenv("SALESFORCE_USERNAME"),
+    password=os.getenv("SALESFORCE_PASSWORD"),
+    security_token=os.getenv("SALESFORCE_SECURITY_TOKEN"),
+)
+if not connector.test_connection():
+    print("Connection failed: check username, password, security token, and domain")
+```
+
+Common causes of authentication failures:
+
+- **Wrong domain**: production orgs use `domain="login"`; sandboxes use `domain="test"`.
+- **Stale security token**: reset it under **Settings → Reset My Security Token**. The new token is emailed to you.
+- **IP restriction**: your org's trusted IP ranges may block the originating IP. Check **Setup → Network Access**.
+- **API access disabled**: ensure the connected profile has the **API Enabled** permission.
+
+
+## See Also
+
+- [Ingest Module](../reference/ingest) — Full `SalesforceIngestor` API and all other ingestors.
+- [Snowflake Integration](snowflake) — Relational warehouse connector with a similar design.
+- [Databricks Integration](databricks) — Lakehouse connector.
+- [Installation](../installation) — All optional dependency extras.
+- [Knowledge Graph](../reference/kg) — Build a KG from ingested Salesforce data.

docs/reference/ingest.md

@@ -28,6 +28,7 @@ icon: "database"
 | `DBIngestor` | SQL databases via SQLAlchemy: tables, views, and custom queries |
 | `SnowflakeIngestor` | Snowflake data warehouse queries and table exports |
 | `DatabricksIngestor` | Databricks Unity Catalog metadata, Delta table queries, and lineage |
+| `SAPIngestor` | SAP OData services (S/4HANA Cloud, SuccessFactors, NetWeaver Gateway): entity-set discovery and ingestion with v2/v4 pagination |
 | `ParquetIngestor` | Apache Parquet files and partitioned datasets with column selection |
 | `ArrowIngestor` | Apache Arrow IPC and Feather file processing |
 | `XMLIngestor` | XXE-safe XML parsing with optional XSD schema validation |

docs/reference/provenance.md

@@ -250,7 +250,7 @@ entry = ProvenanceEntry(
     source_document="report.pdf",     # str: default ""
     source_location="Page 4",         # Optional[str]: default None
     source_quote="Relevant text...",  # Optional[str]: default None
-    timestamp="2024-01-01T12:00:00",  # str: auto-set to utcnow()
+    timestamp="2024-01-01T12:00:00+00:00",  # str: auto-set to utc_now_iso()
     first_seen=None,                  # Optional[str]: ISO timestamp
     last_updated=None,                # Optional[str]: ISO timestamp
     confidence=0.9,                   # float: default 1.0

docs/reference/reasoning.md

@@ -127,9 +127,19 @@ conclusions = reasoner.infer_facts(
 | `forward_chain()` | `List[InferenceResult]` | Derive all possible conclusions iteratively until fixpoint |
 | `backward_chain(goal, max_depth)` | `InferenceResult \| None` | Prove a specific goal string, returns `None` if unprovable |
 | `infer_facts(facts, rules)` | `List[str]` | Load facts and rules then run `forward_chain()`, returns conclusion strings |
-| `clear()` | `None` | Clear all facts and rules |
+| `reset_action_history()` | `None` | Allow actions for previously fired activations to run again |
+| `clear()` | `None` | Clear all facts, rules, and action activation history |
 | `reset()` | `None` | Alias for `clear()` |
 
+Rules with actions use at-most-once attempt semantics per concrete activation
+(rule ID, bindings, and matched facts). Calling `forward_chain()` again on the
+same instance does not repeat side effects for an activation that was already
+attempted, even when an action raised an exception. Call
+`reset_action_history()` to deliberately retry without clearing facts or rules;
+`clear()` and `reset()` also clear this history. Replacing a rule's actions in
+place does not invalidate an existing activation; reset the history explicitly
+when the replacement should be replayed.
+
 ### Rule and Fact dataclass fields
 
 ```python
@@ -230,9 +240,16 @@ engine.reset()
 | `add_fact(fact)` | `None` | Add a `Fact` to working memory and propagate through the network |
 | `match_patterns(facts)` | `List[Match]` | Match all patterns; optionally add facts before matching |
 | `execute_matches(matches)` | `List[Any]` | Execute matched rules and return their conclusion values |
-| `reset()` | `None` | Clear facts and all node activation state |
+| `reset_action_history()` | `None` | Allow actions for previously executed activations to run again |
+| `reset()` | `None` | Clear facts, node activation state, and action activation history |
 | `get_network_stats()` | `dict` | Return counts of alpha, beta, terminal nodes and facts |
 
+When a Reasoner is bound, `execute_matches()` deduplicates action side effects
+by rule ID, bindings, and matched fact identity. Re-executing a match still
+returns its conclusion for compatibility, but its actions are skipped after the
+first attempt. `reset_action_history()`, `reset()`, and `build_network()` allow
+those actions to run again.
+
 
 ## SPARQLReasoner
 

docs/reference/triplet_store.md

@@ -182,7 +182,7 @@ for row in result.bindings:
     store = TripletStore(
         backend="rdf4j",
         endpoint="http://localhost:8080/rdf4j-server",
-        repository_id="semantica",   # passed through **config
+        repository_id="semantica",   # selects the remote repository
     )
     ```
 

docs/reference/utils.md

@@ -77,7 +77,17 @@ Most users won't call utils directly: it's the **shared foundation** for all mod
     export SEMANTICA_LOG_LEVEL=DEBUG
     export SEMANTICA_LOG_FORMAT=json     # "json" | "text"
     export SEMANTICA_DISABLE_PROGRESS=true
+    export SEMANTICA_FORCE_PROGRESS=true
     ```
+
+    <Tip>
+      **Progress bars follow your terminal.** Console progress is written only when
+      stdout is an interactive terminal (or a Jupyter notebook), so piping or
+      redirecting output no longer fills logs with progress bars and escape
+      sequences. Set `SEMANTICA_DISABLE_PROGRESS` to silence progress even in a
+      terminal, or `SEMANTICA_FORCE_PROGRESS` to keep it when stdout is redirected.
+      `SEMANTICA_DISABLE_PROGRESS` wins if both are set.
+    </Tip>
   </Step>
 </Steps>
 

docs/storage-backends.md

@@ -35,7 +35,7 @@ This page is intentionally conservative: it distinguishes between an adapter exi
 | FalkorDB | LPG | Yes | Yes | Partial | Partial | Redis-based; provenance depends on node/edge properties, and multi-graph isolation depends on the selected graph name. |
 | Amazon Neptune | LPG | Yes | Yes | Partial | Partial | Use the property-graph endpoint; AWS auth, VPC, and endpoint configuration can affect local tests. Provenance depends on node/edge properties. |
 | Apache AGE | LPG | Yes | Yes | Partial | Partial | Runs through PostgreSQL/AGE; Cypher compatibility and property handling can differ from standalone LPG engines. |
-| RDF4J | RDF | Yes | Partial | Partial | Partial | Context separation relies on named graphs; triple-level provenance may require reification or graph-level metadata. `RDF4JStore(repository_id=...)` currently has no effect — the constructor always connects to the `"default"` repository regardless of the value passed; track a fix separately. |
+| RDF4J | RDF | Yes | Partial | Partial | Partial | Context separation relies on named graphs; triple-level provenance may require reification or graph-level metadata. |
 | Apache Jena | RDF | Yes | Partial | Partial | Partial | Named graphs are needed for context separation; backend configuration and transaction behavior matter. |
 | Blazegraph | RDF | Yes | Partial | Partial | Partial | Use quads/named graphs for context; IRI stability and graph naming matter for provenance. |
 | Anzo | RDF | Yes | Partial | Partial | Partial | Anzo deployments are environment-specific; validate `dataset_uri`/graphmart naming, named-graph support, and provenance mapping. |
@@ -107,7 +107,7 @@ from semantica.triplet_store import RDF4JStore
 
 store = RDF4JStore(
     endpoint='http://localhost:8080/rdf4j-server',
-    repository_id='semantica'  # currently has no effect; connects to "default" (see Known limitations)
+    repository_id='semantica'
 )
 ```
 

examples/ci/README.md

@@ -0,0 +1,36 @@
+# CI templates
+
+Copy-paste starting points for wiring `semantica` into your own project's CI. Each file is a
+complete, working config — rename it into your project (see the comment at the top of each file
+for the target path) and swap the smoke-test / test step for whatever your project does with
+Semantica. Each template installs `semantica` unconditionally and your own project's dependencies
+only if a `requirements.txt` is present; if your project uses `pyproject.toml`, Poetry, or Pipenv
+instead, adjust the marked install line (each file calls it out inline).
+
+| File | Target path in your repo |
+| ---- | ------------------------- |
+| [`github-actions.yml`](github-actions.yml) | `.github/workflows/semantica.yml` |
+| [`gitlab-ci.yml`](gitlab-ci.yml) | `.gitlab-ci.yml` |
+| [`circleci-config.yml`](circleci-config.yml) | `.circleci/config.yml` |
+
+If your own project is hosted on GitHub, you can skip the setup boilerplate entirely and use
+Semantica's reusable composite action instead:
+
+```yaml
+- uses: semantica-agi/semantica/.github/actions/setup-semantica@main
+  with:
+    python-version: '3.11'
+    # extras: 'explorer,all'   # optional
+    # version: '==0.6.7'       # optional, pin an exact release
+    # cache: 'pip'             # optional, only if your repo has a requirements.txt/pyproject.toml/etc.
+```
+
+`@main` always tracks this repo's default branch, which is convenient but — like any mutable
+ref — can change out from under you between runs. For production CI, pin it to a commit SHA
+instead (find one via `git rev-parse` against a tagged release, or the commit history for
+[`.github/actions/setup-semantica/`](../../.github/actions/setup-semantica/)) and update the pin
+deliberately when you want to pick up changes, the same way this repo's own workflows are pinned
+(see [`verify-action-pins.yml`](../../.github/workflows/verify-action-pins.yml)).
+
+It installs Python, installs `semantica`, and verifies the import (pip caching is opt-in via `cache: 'pip'`, since not every caller repo has a requirements file to key the cache on) — see
+[`.github/actions/setup-semantica/action.yml`](../../.github/actions/setup-semantica/action.yml).

examples/ci/circleci-config.yml

@@ -0,0 +1,40 @@
+# Drop this in as .circleci/config.yml in your own project.
+version: 2.1
+
+jobs:
+  test:
+    docker:
+      - image: cimg/python:3.11
+    steps:
+      - checkout
+      # A content-hashed cache key (e.g. `{{ checksum "requirements.txt" }}`)
+      # is more precise but breaks if that exact file doesn't exist in your
+      # project - swap in one matched to however you declare dependencies
+      # once you've adjusted the install step below.
+      - restore_cache:
+          keys:
+            - pip-cache-v1
+      - run:
+          name: Install dependencies
+          command: |
+            pip install --upgrade pip
+            pip install semantica
+            # Install your own project's dependencies however your project
+            # declares them - adjust this to match, e.g. `pip install -e .`
+            # for pyproject.toml / setup.cfg, or `poetry install`.
+            if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+      - save_cache:
+          key: pip-cache-v1
+          paths:
+            - ~/.cache/pip
+      - run:
+          name: Smoke test
+          command: python -c "import semantica; print('semantica', semantica.__version__)"
+      - run:
+          name: Run tests
+          command: pytest
+
+workflows:
+  test:
+    jobs:
+      - test

examples/ci/github-actions.yml

@@ -0,0 +1,44 @@
+# Drop this in as .github/workflows/semantica.yml in your own project.
+#
+# Installs Semantica and runs a smoke import + your test suite. Swap the
+# smoke-test step for whatever your project actually does with Semantica
+# (build a context graph, run an ingest pipeline, etc.).
+#
+# Third-party actions below are pinned to a commit SHA rather than a mutable
+# tag - a moved tag can silently swap in different code. Update the pin (and
+# the trailing "# vX" comment) deliberately when you want a newer version;
+# see semantica-agi/semantica's own .github/workflows/verify-action-pins.yml
+# for one way to keep pins honest automatically.
+name: Semantica
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install semantica
+          # Install your own project's dependencies however your project
+          # declares them - adjust this to match. Examples:
+          #   pip install -r requirements.txt
+          #   pip install -e .            # pyproject.toml / setup.cfg
+          #   pip install -e ".[dev]"
+          #   poetry install
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+
+      - name: Run tests
+        run: pytest

examples/ci/gitlab-ci.yml

@@ -0,0 +1,20 @@
+# Drop this in as .gitlab-ci.yml in your own project.
+semantica-test:
+  image: python:3.11-slim
+  cache:
+    paths:
+      - .cache/pip
+  variables:
+    PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+  script:
+    - pip install --upgrade pip
+    - pip install semantica
+    # Install your own project's dependencies however your project declares
+    # them - adjust this to match, e.g. `pip install -e .` for pyproject.toml
+    # / setup.cfg, or `poetry install`.
+    - if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    - python -c "import semantica; print('semantica', semantica.__version__)"
+    - pytest
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'

examples/explorer_deterministic_rendering_example.py

@@ -0,0 +1,195 @@
+"""
+Deterministic Explorer Rendering E2E Example.
+
+Demonstrates building, serializing, and reloading a deterministic 4-node,
+3-edge knowledge graph baseline for visual inspection in Semantica Explorer (#1037).
+
+Graph topology:
+    Alice (Person, #63E6FF)       --WORKS_AT-->    Acme (Organization, #A78BFA)
+    Bob (Person, #63E6FF)         --KNOWS-->       Alice (Person, #63E6FF)
+    Acme (Organization, #A78BFA)  --LOCATED_IN-->  New York (Location, #34D399)
+
+Clean Checkout Prerequisites:
+    1. Python backend dependencies:
+       pip install -e ".[explorer]"
+    2. Frontend workspace dependencies:
+       cd explorer && npm install && cd ..
+
+Usage:
+    # 1. Generate the deterministic graph baseline:
+    python examples/explorer_deterministic_rendering_example.py
+
+    # 2. Launch Explorer with local dev authentication (Option A - Dev mode):
+    # Terminal 1 (Backend API):
+    SEMANTICA_ALLOW_ANONYMOUS=true python -m semantica.explorer --graph explorer_e2e_test_graph.json --port 8000 --no-browser
+    # Terminal 2 (Frontend UI):
+    cd explorer && npm run dev
+    # Open http://localhost:5173
+
+    # 2. Launch Explorer (Option B - Standalone CLI server):
+    SEMANTICA_ALLOW_ANONYMOUS=true python -m semantica.explorer --graph explorer_e2e_test_graph.json --port 8000
+    # Open http://localhost:8000
+
+    # Secure authentication alternative:
+    export SEMANTICA_API_KEY="your-secret-api-key"
+    python -m semantica.explorer --graph explorer_e2e_test_graph.json --port 8000
+    # Send HTTP header: X-API-Key: your-secret-api-key
+
+Verification Checklist:
+    - Exactly 4 nodes visible on canvas:
+        * Alice (Person, #63E6FF)
+        * Bob (Person, #63E6FF)
+        * Acme (Organization, #A78BFA)
+        * New York (Location, #34D399)
+    - Exactly 3 directed edges with canonical relationship labels:
+        * Alice -> Acme  (WORKS_AT)
+        * Bob -> Alice   (KNOWS)
+        * Acme -> New York (LOCATED_IN)
+    - Zoom behavior:
+        * Zoom in to Inspection tier (ratio <= 0.5): directional arrows and node labels scale clearly.
+        * Zoom out to Overview tier (ratio > 1.2): layout remains stable and non-colliding.
+    - Hover & Selection interactions:
+        * Hover over 'Alice': node halo triggers; incident edges (WORKS_AT, KNOWS) highlight in local context.
+        * Click an edge: Inspector panel confirms edgeType ('WORKS_AT', 'KNOWS', or 'LOCATED_IN').
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from semantica.context.context_graph import ContextGraph
+from semantica.explorer.session import GraphSession
+
+
+def build_deterministic_graph() -> ContextGraph:
+    """Build the exact 4-node, 3-edge graph specified in #1037."""
+    graph = ContextGraph(advanced_analytics=False)
+
+    # 1. Add exactly 4 nodes
+    graph.add_node(
+        "alice",
+        node_type="Person",
+        content="Alice",
+        color="#63E6FF",
+    )
+    graph.add_node(
+        "bob",
+        node_type="Person",
+        content="Bob",
+        color="#63E6FF",
+    )
+    graph.add_node(
+        "acme",
+        node_type="Organization",
+        content="Acme",
+        color="#A78BFA",
+    )
+    graph.add_node(
+        "new_york",
+        node_type="Location",
+        content="New York",
+        color="#34D399",
+    )
+
+    # 2. Add exactly 3 directed edges
+    graph.add_edge("alice", "acme", edge_type="WORKS_AT", weight=1.0)
+    graph.add_edge("bob", "alice", edge_type="KNOWS", weight=1.0)
+    graph.add_edge("acme", "new_york", edge_type="LOCATED_IN", weight=1.0)
+
+    return graph
+
+
+def main() -> None:
+    print("=" * 75)
+    print("Semantica Explorer Deterministic Graph Generator (#1037)")
+    print("=" * 75)
+
+    print("1. Building deterministic ContextGraph...")
+    graph = build_deterministic_graph()
+    print(
+        f"   ✓ Graph built with {len(graph.nodes)} nodes "
+        f"and {len(graph.edges)} edges."
+    )
+
+    output_path = Path("explorer_e2e_test_graph.json").resolve()
+    print(f"2. Persisting graph to '{output_path.name}'...")
+    graph.save_to_file(str(output_path))
+    print(f"   ✓ Graph saved to {output_path}")
+
+    # Verify JSON format
+    with open(output_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    assert len(data.get("nodes", [])) == 4
+    assert len(data.get("edges", [])) == 3
+
+    print("3. Verifying reload via GraphSession.from_file()...")
+    session = GraphSession.from_file(str(output_path))
+    stats = session.get_stats()
+    nodes, total_nodes = session.get_nodes()
+    edges, total_edges = session.get_edges()
+
+    assert stats["node_count"] == 4
+    assert stats["edge_count"] == 3
+    assert total_nodes == 4
+    assert total_edges == 3
+
+    print(
+        f"   ✓ Graph reloaded successfully without mutation "
+        f"(nodes: {total_nodes}, edges: {total_edges}).\n"
+    )
+
+    print("=" * 75)
+    print("Clean Checkout Prerequisites:")
+    print("=" * 75)
+    print("    pip install -e '.[explorer]'")
+    print("    cd explorer && npm install && cd ..\n")
+
+    print("=" * 75)
+    print("Reproduction instructions to view in Semantica Explorer:")
+    print("=" * 75)
+    print("Option A (Frontend dev server + API backend — recommended for development):")
+    print(
+        f"    1. Backend:  SEMANTICA_ALLOW_ANONYMOUS=true python -m semantica.explorer "
+        f"--graph {output_path} --port 8000 --no-browser"
+    )
+    print("    2. Frontend: cd explorer && npm run dev")
+    print("    3. Open http://localhost:5173 to inspect the graph canvas.\n")
+
+    print("Option B (Standalone Explorer CLI server):")
+    print(
+        f"    SEMANTICA_ALLOW_ANONYMOUS=true python -m semantica.explorer "
+        f"--graph {output_path} --port 8000"
+    )
+    print("    Open http://localhost:8000\n")
+
+    print("Secure Authentication Alternative:")
+    print("    export SEMANTICA_API_KEY='your-secret-api-key'")
+    print(
+        f"    python -m semantica.explorer --graph {output_path} --port 8000"
+    )
+    print("    Send header: 'X-API-Key: your-secret-api-key'\n")
+
+    print("=" * 75)
+    print("Verification Checklist:")
+    print("=" * 75)
+    print("    1. Nodes (4 total):")
+    print("       - Alice (Person, #63E6FF)")
+    print("       - Bob (Person, #63E6FF)")
+    print("       - Acme (Organization, #A78BFA)")
+    print("       - New York (Location, #34D399)")
+    print("    2. Directed Edges & Canonical Labels (3 total):")
+    print("       - Alice -> Acme     [WORKS_AT]")
+    print("       - Bob   -> Alice    [KNOWS]")
+    print("       - Acme  -> New York [LOCATED_IN]")
+    print("    3. Zoom Interactions:")
+    print("       - Inspection tier (zoom in): directional arrows & labels remain legible.")
+    print("       - Overview tier (zoom out): nodes and edges maintain layout integrity.")
+    print("    4. Hover & Selection Interactions:")
+    print("       - Hover Alice: node halo triggers and incident edges (WORKS_AT, KNOWS) highlight.")
+    print("       - Click edge: Inspector panel displays edgeType label ('WORKS_AT', 'KNOWS', 'LOCATED_IN').")
+    print("=" * 75)
+
+
+if __name__ == "__main__":
+    main()

explorer/package-lock.json

@@ -2083,9 +2083,9 @@
       }
     },
     "node_modules/brace-expansion": {
-      "version": "5.0.8",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.8.tgz",
-      "integrity": "sha512-JZyDyq3D4AUifKTPOB7DELf6XsB3WdPuNxCtob1vFXPsSXhdAiHBWJ/tJ8HAc9aH84BK+5JFZLNkJKx3G9kzQg==",
+      "version": "5.0.9",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.9.tgz",
+      "integrity": "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -4250,9 +4250,9 @@
       "license": "MIT"
     },
     "node_modules/nanoid": {
-      "version": "3.3.16",
-      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.16.tgz",
-      "integrity": "sha512-bzlKTyNJ7+LdGIIwy8ijFpIqEQIvafahV7eYykJ8Cvh42EdJeODoJ6gUJXpQJvej1BddH8OqTXZNE/KfbWAu8Q==",
+      "version": "3.3.18",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz",
+      "integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==",
       "dev": true,
       "funding": [
         {

explorer/package.json

@@ -9,7 +9,8 @@
     "lint": "eslint .",
     "preview": "vite preview",
     "test:graph-store": "node --test tests/graphStore.multi-edge.test.mjs",
-    "test:graph-workspace": "node --import tsx --test tests/markdownContentViewer.test.ts tests/graphSceneState.display.test.ts tests/temporalLifecycle.test.ts",
+    "test:graph-workspace": "node --import tsx --test tests/markdownContentViewer.test.ts tests/graphSceneState.display.test.ts tests/temporalLifecycle.test.ts tests/deterministicExplorerRendering.test.ts",
+    "test:deterministic-e2e": "node --import tsx --test tests/deterministicExplorerRendering.e2e.ts",
     "test:plugin-registry": "node --import tsx --test tests/pluginRegistry.temporal.test.mjs"
   },
   "dependencies": {

explorer/src/workspaces/GraphWorkspace/GraphWorkspace.tsx

@@ -41,6 +41,7 @@ import {
 } from "./plugins";
 import { explorationEffectsShouldLoad, neighborhoodPanelShouldLoad, temporalOverlayShouldLoad } from "./pluginRegistryPredicates";
 import { shouldFetchTemporalBounds, shouldFetchTemporalSnapshot } from "./temporalLifecyclePredicates";
+import { createTemporalSnapshotGuards, type TemporalSnapshotResponse } from "./temporalSnapshotGuards";
 import type { LinkPrediction, PathResponse } from "./GraphInspectorPanel";
 import type { GraphSceneHandle, GraphSceneRuntime } from "./scene";
 import type {
@@ -1479,6 +1480,23 @@ export function GraphWorkspace({ externalFocusNodeId, externalFocusToken }: Grap
     summary?.edgeCount,
   ]);
 
+  // Guards the snapshot lifecycle: at most one in-flight request per scrubber
+  // position (identical-`at` polls are deduplicated, breaking the idle/play
+  // polling loop), applied snapshots are cached and re-applied on revisit, and
+  // a response applies only while the scrubber is still on its position
+  // (out-of-order responses cannot clobber the active-node count).
+  const temporalSnapshotGuardsRef = useRef<ReturnType<typeof createTemporalSnapshotGuards> | null>(null);
+  if (temporalSnapshotGuardsRef.current === null) {
+    temporalSnapshotGuardsRef.current = createTemporalSnapshotGuards();
+  }
+  const temporalSnapshotGuards = temporalSnapshotGuardsRef.current;
+
+  // A new graph summary means the graph data was replaced (reload/retry);
+  // snapshots cached against the previous graph are stale, so reset all state.
+  useEffect(() => {
+    temporalSnapshotGuards.reset();
+  }, [summary]);
+
   useEffect(() => {
     if (!canFetchTemporalSnapshot) {
       return;
@@ -1488,37 +1506,67 @@ export function GraphWorkspace({ externalFocusNodeId, externalFocusToken }: Grap
       return;
     }
 
+    const atMs = debouncedTime.getTime();
+    const { seq, cached } = temporalSnapshotGuards.begin(atMs);
+    if (seq === null) {
+      // An identical request is already in flight: one request per position.
+      return;
+    }
+
     let cancelled = false;
 
+    const applyData = (data: TemporalSnapshotResponse) => {
+      const nextActiveIds = new Set(data.active_node_ids);
+      requestAnimationFrame(() => {
+        if (cancelled) return;
+        if (!temporalSnapshotGuards.shouldApply(atMs, seq)) {
+          // The scrubber moved on (or this request was superseded): release the
+          // position so a return to it refetches instead of stalling.
+          temporalSnapshotGuards.finish(atMs, seq);
+          return;
+        }
+        const previous = prevActiveIdsRef.current;
+        previous.forEach((id) => {
+          if (!nextActiveIds.has(id) && graph.hasNode(id)) {
+            graph.setNodeAttribute(id, "hidden", true);
+          }
+        });
+        nextActiveIds.forEach((id) => {
+          if (graph.hasNode(id)) {
+            graph.setNodeAttribute(id, "hidden", false);
+          }
+        });
+        prevActiveIdsRef.current = nextActiveIds;
+        setActiveNodeCount(data.active_node_count);
+        setGraphVersion((current) => current + 1);
+        sceneRef.current?.getRuntime()?.requestRender();
+        temporalSnapshotGuards.apply(atMs, seq, data);
+      });
+    };
+
+    if (cached) {
+      // Returning to a position whose snapshot was already applied: re-apply
+      // the cached result without a network request.
+      applyData(cached);
+      return;
+    }
+
     const applySnapshot = async () => {
       try {
         const at = debouncedTime.toISOString();
         const response = await fetch(`/api/temporal/snapshot?at=${encodeURIComponent(at)}`);
-        if (!response.ok || cancelled) return;
-
-        const data: { active_node_ids: string[]; active_node_count: number } = await response.json();
+        if (!response.ok) {
+          // A failed request must be retryable if the scrubber returns.
+          if (!cancelled) temporalSnapshotGuards.finish(atMs, seq);
+          return;
+        }
         if (cancelled) return;
 
-        const nextActiveIds = new Set(data.active_node_ids);
-        requestAnimationFrame(() => {
-          if (cancelled) return;
-          const previous = prevActiveIdsRef.current;
-          previous.forEach((id) => {
-            if (!nextActiveIds.has(id) && graph.hasNode(id)) {
-              graph.setNodeAttribute(id, "hidden", true);
-            }
-          });
-          nextActiveIds.forEach((id) => {
-            if (graph.hasNode(id)) {
-              graph.setNodeAttribute(id, "hidden", false);
-            }
-          });
-          prevActiveIdsRef.current = nextActiveIds;
-          setActiveNodeCount(data.active_node_count);
-          setGraphVersion((current) => current + 1);
-          sceneRef.current?.getRuntime()?.requestRender();
-        });
+        const data: TemporalSnapshotResponse = await response.json();
+        if (cancelled) return;
+        applyData(data);
       } catch (fetchError) {
+        temporalSnapshotGuards.finish(atMs, seq);
         if (!cancelled) {
           console.error("[Temporal] Snapshot fetch failed", fetchError);
         }
@@ -1528,6 +1576,8 @@ export function GraphWorkspace({ externalFocusNodeId, externalFocusToken }: Grap
     applySnapshot();
     return () => {
       cancelled = true;
+      // A cancelled request must be retryable when its position is revisited.
+      temporalSnapshotGuards.finish(atMs, seq);
     };
   }, [
     canFetchTemporalSnapshot,

explorer/src/workspaces/GraphWorkspace/MarkdownContentViewer.tsx

@@ -1,8 +1,9 @@
-import { useState, useRef, useEffect, type CSSProperties } from "react";
-import ReactMarkdown from "react-markdown";
+import { useState, useRef, useEffect, useMemo, type CSSProperties } from "react";
+import ReactMarkdown, { type Components } from "react-markdown";
 import remarkGfm from "remark-gfm";
 import { Check, Copy, Code2, Eye, ExternalLink, Image as ImageIcon } from "lucide-react";
 import { GRAPH_THEME } from "./graphTheme";
+import { isSafeUrl } from "./markdownUrlSafety";
 
 export interface MarkdownContentViewerProps {
   content?: string | null;
@@ -10,25 +11,6 @@ export interface MarkdownContentViewerProps {
   defaultMode?: "preview" | "source";
 }
 
-export function isSafeUrl(url?: string): boolean {
-  if (!url) return false;
-  const trimmed = url.trim();
-  // Reject whitespace-only strings — new URL("", base) would resolve to the base
-  // protocol and produce a false positive. This guards direct callers of the exported
-  // function; markdown parsers normalise whitespace-only destinations to "" which
-  // already fails the !url check above.
-  if (!trimmed) return false;
-  if (trimmed.startsWith("//")) return false;
-  if (trimmed.startsWith("#")) return true;
-  if (trimmed.startsWith("/")) return true;
-  try {
-    const parsed = new URL(trimmed, "http://localhost");
-    return ["http:", "https:", "mailto:"].includes(parsed.protocol);
-  } catch {
-    return false;
-  }
-}
-
 export function MarkdownContentViewer({
   content,
   className,
@@ -65,6 +47,20 @@ export function MarkdownContentViewer({
   const rawContent = typeof content === "string" ? content : "";
   const hasContent = rawContent.trim().length > 0;
 
+  // react-markdown runs the whole remark pipeline synchronously inside its own
+  // render, so without this memo every unrelated re-render of this component --
+  // clicking Copy, toggling Preview/Source -- re-parses the entire document.
+  // Measured at ~364ms per re-render for a 1000-row GFM table (issue #1118).
+  // Keyed on rawContent so a genuine node change still re-parses exactly once.
+  const renderedMarkdown = useMemo(
+    () => (
+      <ReactMarkdown remarkPlugins={REMARK_PLUGINS} components={MARKDOWN_COMPONENTS}>
+        {rawContent}
+      </ReactMarkdown>
+    ),
+    [rawContent],
+  );
+
   const handleCopy = async () => {
     if (!hasContent) return;
     try {
@@ -130,98 +126,103 @@ export function MarkdownContentViewer({
             <code style={sourceCodeStyle}>{rawContent}</code>
           </pre>
         ) : (
-          <div style={previewStyle}>
-            <ReactMarkdown
-              remarkPlugins={[remarkGfm]}
-              components={{
-                // C-1: react-markdown passes a HAST `node` prop (the raw AST
-                // Element) to every custom component override via passNode:true.
-                // In React 19 any unknown prop spreads onto a native element are
-                // serialised as HTML attributes, producing node="[object Object]"
-                // on every rendered link. Fix: destructure `node` by name so it
-                // is explicitly discarded, then spread `...rest` to preserve all
-                // other legitimate HAST/remark-gfm attributes — e.g. the `id`,
-                // `aria-describedby`, `aria-label`, `data-footnote-ref`,
-                // `data-footnote-backref`, and `class` attrs that GFM footnotes
-                // require for correct in-page navigation and accessibility.
-                //
-                // C-2: fragment links (#anchor, GFM footnote backlinks) must
-                // navigate within the current document. External links continue
-                // to use target="_blank" with noopener noreferrer.
-                //
-                // eslint-disable-next-line @typescript-eslint/no-unused-vars
-                a: ({ href, children, title, node: _node, ...rest }) => {
-                  if (!isSafeUrl(href)) {
-                    return <span style={{ color: GRAPH_THEME.ui.text.muted, textDecoration: "line-through" }}>{children}</span>;
-                  }
-                  // isSafeUrl returning true guarantees href is a non-empty string.
-                  const safeHref = href ?? "";
-                  // Fragment links (#section, footnote backlinks like
-                  // #user-content-fnref-1) are in-document anchors. Opening them
-                  // in a new tab would break GFM footnote back-navigation.
-                  const isFragment = safeHref.startsWith("#");
-                  if (isFragment) {
-                    return (
-                      <a href={safeHref} title={title} style={linkStyle} {...rest}>
-                        {children}
-                      </a>
-                    );
-                  }
-                  return (
-                    <a href={safeHref} title={title} target="_blank" rel="noopener noreferrer" style={linkStyle} {...rest}>
-                      {children}
-                      <ExternalLink size={10} style={{ marginLeft: 3, verticalAlign: "middle", display: "inline" }} />
-                    </a>
-                  );
-                },
-                img: ({ src, alt }) => (
-                  <span style={imageBadgeStyle} title={src || "Image"}>
-                    <ImageIcon size={12} style={{ marginRight: 5 }} />
-                    <span>Image: {alt || src || "unlabeled"}</span>
-                  </span>
-                ),
-                h1: ({ children }) => <h1 style={h1Style}>{children}</h1>,
-                h2: ({ children }) => <h2 style={h2Style}>{children}</h2>,
-                h3: ({ children }) => <h3 style={h3Style}>{children}</h3>,
-                h4: ({ children }) => <h4 style={h4Style}>{children}</h4>,
-                p: ({ children }) => <p style={{ margin: "0 0 8px 0" }}>{children}</p>,
-                ul: ({ children }) => <ul style={{ margin: "0 0 8px 0", paddingLeft: 18 }}>{children}</ul>,
-                ol: ({ children }) => <ol style={{ margin: "0 0 8px 0", paddingLeft: 18 }}>{children}</ol>,
-                li: ({ children }) => <li style={{ marginBottom: 3 }}>{children}</li>,
-                blockquote: ({ children }) => <blockquote style={blockquoteStyle}>{children}</blockquote>,
-                hr: () => <hr style={{ border: "none", borderTop: `1px solid ${GRAPH_THEME.ui.surface.panelBorder}`, margin: "10px 0" }} />,
-                table: ({ children }) => (
-                  <div style={{ width: "100%", overflowX: "auto", margin: "8px 0", borderRadius: 6, border: `1px solid ${GRAPH_THEME.ui.surface.panelBorder}` }}>
-                    <table style={{ width: "100%", borderCollapse: "collapse", fontSize: 12 }}>{children}</table>
-                  </div>
-                ),
-                thead: ({ children }) => <thead style={{ background: "rgba(255, 255, 255, 0.04)" }}>{children}</thead>,
-                tbody: ({ children }) => <tbody>{children}</tbody>,
-                tr: ({ children }) => <tr style={{ borderBottom: `1px solid ${GRAPH_THEME.ui.surface.panelBorder}` }}>{children}</tr>,
-                th: ({ children }) => <th style={{ padding: "6px 8px", textAlign: "left", fontWeight: 700, color: GRAPH_THEME.ui.text.strong, borderRight: `1px solid ${GRAPH_THEME.ui.surface.panelBorder}` }}>{children}</th>,
-                td: ({ children }) => <td style={{ padding: "6px 8px", color: GRAPH_THEME.ui.text.body, borderRight: `1px solid ${GRAPH_THEME.ui.surface.panelBorder}` }}>{children}</td>,
-                pre: ({ children }) => <pre style={preBlockStyle}>{children}</pre>,
-                // C-1: discard `node` here too — code elements are custom components
-                // and would otherwise receive node="[object Object]" in the DOM.
-                code: ({ className: codeClass, children }) => {
-                  const isInline = !codeClass && typeof children === "string" && !children.includes("\n");
-                  return (
-                    <code style={isInline ? inlineCodeStyle : blockCodeStyle}>
-                      {children}
-                    </code>
-                  );
-                },
-              }}
-            >
-              {rawContent}
-            </ReactMarkdown>
-          </div>
+          <div style={previewStyle}>{renderedMarkdown}</div>
         )}
       </div>
     </div>
   );
 }
 
+/* ─── Markdown rendering config ───────────────────────────────────── */
+
+// Both props are hoisted to module scope so they keep a stable identity across
+// renders. As inline literals they allocated a fresh plugin array and ~20 fresh
+// arrow components on every render, which made React treat every mapped tag as a
+// new element type and remount the entire rendered subtree instead of updating
+// it (issue #1118). The arrow bodies only read the style constants below at call
+// time, so declaring the map before them is safe.
+const REMARK_PLUGINS = [remarkGfm];
+
+const MARKDOWN_COMPONENTS: Components = {
+  // C-1: react-markdown passes a HAST `node` prop (the raw AST
+  // Element) to every custom component override via passNode:true.
+  // In React 19 any unknown prop spreads onto a native element are
+  // serialised as HTML attributes, producing node="[object Object]"
+  // on every rendered link. Fix: destructure `node` by name so it
+  // is explicitly discarded, then spread `...rest` to preserve all
+  // other legitimate HAST/remark-gfm attributes — e.g. the `id`,
+  // `aria-describedby`, `aria-label`, `data-footnote-ref`,
+  // `data-footnote-backref`, and `class` attrs that GFM footnotes
+  // require for correct in-page navigation and accessibility.
+  //
+  // C-2: fragment links (#anchor, GFM footnote backlinks) must
+  // navigate within the current document. External links continue
+  // to use target="_blank" with noopener noreferrer.
+  //
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  a: ({ href, children, title, node: _node, ...rest }) => {
+    if (!isSafeUrl(href)) {
+      return <span style={{ color: GRAPH_THEME.ui.text.muted, textDecoration: "line-through" }}>{children}</span>;
+    }
+    // isSafeUrl returning true guarantees href is a non-empty string.
+    const safeHref = href ?? "";
+    // Fragment links (#section, footnote backlinks like
+    // #user-content-fnref-1) are in-document anchors. Opening them
+    // in a new tab would break GFM footnote back-navigation.
+    const isFragment = safeHref.startsWith("#");
+    if (isFragment) {
+      return (
+        <a href={safeHref} title={title} style={linkStyle} {...rest}>
+          {children}
+        </a>
+      );
+    }
+    return (
+      <a href={safeHref} title={title} target="_blank" rel="noopener noreferrer" style={linkStyle} {...rest}>
+        {children}
+        <ExternalLink size={10} style={{ marginLeft: 3, verticalAlign: "middle", display: "inline" }} />
+      </a>
+    );
+  },
+  img: ({ src, alt }) => (
+    <span style={imageBadgeStyle} title={src || "Image"}>
+      <ImageIcon size={12} style={{ marginRight: 5 }} />
+      <span>Image: {alt || src || "unlabeled"}</span>
+    </span>
+  ),
+  h1: ({ children }) => <h1 style={h1Style}>{children}</h1>,
+  h2: ({ children }) => <h2 style={h2Style}>{children}</h2>,
+  h3: ({ children }) => <h3 style={h3Style}>{children}</h3>,
+  h4: ({ children }) => <h4 style={h4Style}>{children}</h4>,
+  p: ({ children }) => <p style={{ margin: "0 0 8px 0" }}>{children}</p>,
+  ul: ({ children }) => <ul style={{ margin: "0 0 8px 0", paddingLeft: 18 }}>{children}</ul>,
+  ol: ({ children }) => <ol style={{ margin: "0 0 8px 0", paddingLeft: 18 }}>{children}</ol>,
+  li: ({ children }) => <li style={{ marginBottom: 3 }}>{children}</li>,
+  blockquote: ({ children }) => <blockquote style={blockquoteStyle}>{children}</blockquote>,
+  hr: () => <hr style={{ border: "none", borderTop: `1px solid ${GRAPH_THEME.ui.surface.panelBorder}`, margin: "10px 0" }} />,
+  table: ({ children }) => (
+    <div style={{ width: "100%", overflowX: "auto", margin: "8px 0", borderRadius: 6, border: `1px solid ${GRAPH_THEME.ui.surface.panelBorder}` }}>
+      <table style={{ width: "100%", borderCollapse: "collapse", fontSize: 12 }}>{children}</table>
+    </div>
+  ),
+  thead: ({ children }) => <thead style={{ background: "rgba(255, 255, 255, 0.04)" }}>{children}</thead>,
+  tbody: ({ children }) => <tbody>{children}</tbody>,
+  tr: ({ children }) => <tr style={{ borderBottom: `1px solid ${GRAPH_THEME.ui.surface.panelBorder}` }}>{children}</tr>,
+  th: ({ children }) => <th style={{ padding: "6px 8px", textAlign: "left", fontWeight: 700, color: GRAPH_THEME.ui.text.strong, borderRight: `1px solid ${GRAPH_THEME.ui.surface.panelBorder}` }}>{children}</th>,
+  td: ({ children }) => <td style={{ padding: "6px 8px", color: GRAPH_THEME.ui.text.body, borderRight: `1px solid ${GRAPH_THEME.ui.surface.panelBorder}` }}>{children}</td>,
+  pre: ({ children }) => <pre style={preBlockStyle}>{children}</pre>,
+  // C-1: discard `node` here too — code elements are custom components
+  // and would otherwise receive node="[object Object]" in the DOM.
+  code: ({ className: codeClass, children }) => {
+    const isInline = !codeClass && typeof children === "string" && !children.includes("\n");
+    return (
+      <code style={isInline ? inlineCodeStyle : blockCodeStyle}>
+        {children}
+      </code>
+    );
+  },
+};
+
 /* ─── Styles ──────────────────────────────────────────────────────── */
 
 const viewerContainerStyle: CSSProperties = {

explorer/src/workspaces/GraphWorkspace/markdownUrlSafety.ts

@@ -0,0 +1,29 @@
+/**
+ * URL-safety predicate for the Markdown content viewer.
+ *
+ * Extracted into a pure module so the check can be unit-tested without
+ * importing the MarkdownContentViewer React component, and so the component
+ * module exports only components (react-refresh/only-export-components,
+ * issue #1119). The behaviour is unchanged from the original in-component
+ * implementation: only http, https, mailto, in-document fragments, and
+ * root-relative paths are permitted.
+ */
+
+export function isSafeUrl(url?: string): boolean {
+  if (!url) return false;
+  const trimmed = url.trim();
+  // Reject whitespace-only strings — new URL("", base) would resolve to the base
+  // protocol and produce a false positive. This guards direct callers of the exported
+  // function; markdown parsers normalise whitespace-only destinations to "" which
+  // already fails the !url check above.
+  if (!trimmed) return false;
+  if (trimmed.startsWith("//")) return false;
+  if (trimmed.startsWith("#")) return true;
+  if (trimmed.startsWith("/")) return true;
+  try {
+    const parsed = new URL(trimmed, "http://localhost");
+    return ["http:", "https:", "mailto:"].includes(parsed.protocol);
+  } catch {
+    return false;
+  }
+}

explorer/src/workspaces/GraphWorkspace/temporalSnapshotGuards.ts

@@ -0,0 +1,113 @@
+/**
+ * Guards for the temporal snapshot fetch/apply lifecycle.
+ *
+ * The snapshot effect previously fetched /api/temporal/snapshot with no
+ * idempotency or ordering protection. Upstream churn (timeline recreation
+ * while bounds settle, play ticks resetting the playhead, drag events) could
+ * re-request the same `at` repeatedly, and responses could arrive after the
+ * scrubber had moved on.
+ *
+ * The guards enforce:
+ * - at most one in-flight request per scrubber position (identical `at`
+ *   values are deduplicated while a request is pending, breaking the
+ *   idle/play polling loop);
+ * - successful snapshots are cached per position and re-applied when the
+ *   scrubber returns (play wrap-around, back-scrubbing) without a refetch;
+ * - a response is applied only while the scrubber is still on its position,
+ *   so out-of-order responses cannot clobber a newer position's count;
+ * - failed, cancelled, or superseded requests release their position so it
+ *   can be fetched again on the next visit;
+ * - `reset()` drops all state when the underlying graph data is replaced
+ *   (reload/retry), because cached snapshots describe the previous graph.
+ *
+ * `createTemporalSnapshotGuards()` is stateful by design.
+ */
+
+export interface TemporalSnapshotResponse {
+  active_node_ids: string[];
+  active_node_count: number;
+}
+
+export interface TemporalSnapshotRequest {
+  /** null when the request was deduplicated because one is already in flight. */
+  seq: number | null;
+  /** The snapshot previously applied for this position, when revisiting it. */
+  cached: TemporalSnapshotResponse | null;
+}
+
+export interface TemporalSnapshotGuards {
+  /** Begin (or dedupe) a request for `atMs`; marks it as the current position. */
+  begin(atMs: number): TemporalSnapshotRequest;
+  /** True when the response for `atMs`/`seq` may be applied (scrubber still on `atMs`). */
+  shouldApply(atMs: number, seq: number): boolean;
+  /** Record a successful application and cache its snapshot for revisits. */
+  apply(atMs: number, seq: number, data: TemporalSnapshotResponse): void;
+  /** Release a position whose request failed, was cancelled, or was superseded. */
+  finish(atMs: number, seq: number): void;
+  /** Drop all state; call when the underlying graph data is replaced (reload). */
+  reset(): void;
+}
+
+interface SnapshotEntry {
+  seq: number;
+  /** null while the request is in flight (or before the first success). */
+  data: TemporalSnapshotResponse | null;
+}
+
+/** Upper bound on cached positions so long scrubbing sessions stay bounded. */
+const MAX_CACHED_POSITIONS = 256;
+
+export function createTemporalSnapshotGuards(): TemporalSnapshotGuards {
+  const entries = new Map<number, SnapshotEntry>();
+  let latestRequestSeq = 0;
+  let currentAtMs: number | null = null;
+
+  const evictOldest = () => {
+    while (entries.size > MAX_CACHED_POSITIONS) {
+      const oldestAtMs = entries.keys().next().value;
+      if (oldestAtMs === undefined) return;
+      entries.delete(oldestAtMs);
+    }
+  };
+
+  return {
+    begin(atMs) {
+      const existing = entries.get(atMs);
+      if (existing && existing.data === null) {
+        // Identical request already in flight: dedupe, but the scrubber is here now.
+        currentAtMs = atMs;
+        return { seq: null, cached: null };
+      }
+      latestRequestSeq += 1;
+      const seq = latestRequestSeq;
+      entries.set(atMs, { seq, data: existing?.data ?? null });
+      currentAtMs = atMs;
+      evictOldest();
+      return { seq, cached: existing?.data ?? null };
+    },
+
+    shouldApply(atMs, seq) {
+      return atMs === currentAtMs && entries.get(atMs)?.seq === seq;
+    },
+
+    apply(atMs, seq, data) {
+      const entry = entries.get(atMs);
+      if (entry && entry.seq === seq) {
+        entry.data = data;
+      }
+    },
+
+    finish(atMs, seq) {
+      const entry = entries.get(atMs);
+      if (entry && entry.seq === seq && entry.data === null) {
+        entries.delete(atMs);
+      }
+    },
+
+    reset() {
+      entries.clear();
+      latestRequestSeq = 0;
+      currentAtMs = null;
+    },
+  };
+}

explorer/src/workspaces/GraphWorkspace/useLoadGraph.ts

@@ -318,6 +318,20 @@ interface EdgeListResponse {
 
 const PAGE_LIMIT = 1000;
 
+/** Surface the server's `detail` message (e.g. auth/setup guidance) on non-OK responses. */
+async function fetchErrorDetail(response: Response): Promise<string> {
+  try {
+    const body: unknown = await response.json();
+    const detail = (body as { detail?: unknown } | null)?.detail;
+    if (typeof detail === "string" && detail.trim()) {
+      return ` — ${detail.trim()}`;
+    }
+  } catch {
+    // Non-JSON or unreadable body: fall back to the status-only message.
+  }
+  return "";
+}
+
 async function fetchAllNodes(
   signal: AbortSignal,
   onProgress?: (progress: GraphLoadProgress) => void,
@@ -335,7 +349,7 @@ async function fetchAllNodes(
 
     const response = await fetch(url.toString(), { signal });
     if (!response.ok) {
-      throw new Error(`Fetch failed: ${response.status}`);
+      throw new Error(`Fetch failed: ${response.status}${await fetchErrorDetail(response)}`);
     }
 
     const data: NodeListResponse = await response.json();
@@ -390,7 +404,7 @@ async function fetchAllEdges(
 
     const response = await fetch(url.toString(), { signal });
     if (!response.ok) {
-      throw new Error(`Fetch failed: ${response.status}`);
+      throw new Error(`Fetch failed: ${response.status}${await fetchErrorDetail(response)}`);
     }
 
     const data: EdgeListResponse = await response.json();

explorer/tests/deterministicExplorerRendering.e2e.ts

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync } from "node:fs";
+import { setTimeout as delay } from "node:timers/promises";
+import test from "node:test";
+import { chromium, type Page } from "playwright";
+
+const PORT = 4173;
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+
+const nodes = [
+  { id: "alice", type: "Person", content: "Alice", properties: {} },
+  { id: "bob", type: "Person", content: "Bob", properties: {} },
+  { id: "acme", type: "Organization", content: "Acme", properties: {} },
+  { id: "new_york", type: "Location", content: "New York", properties: {} },
+];
+
+const edges = [
+  { id: "edge_alice_acme", familyId: "edge_alice_acme", source: "alice", target: "acme", type: "WORKS_AT", weight: 1, properties: {} },
+  { id: "edge_bob_alice", familyId: "edge_bob_alice", source: "bob", target: "alice", type: "KNOWS", weight: 1, properties: {} },
+  { id: "edge_acme_new_york", familyId: "edge_acme_new_york", source: "acme", target: "new_york", type: "LOCATED_IN", weight: 1, properties: {} },
+];
+
+let server: ChildProcess | undefined;
+
+async function startVite(): Promise<void> {
+  server = spawn("npm", ["run", "dev", "--", "--host", "127.0.0.1", "--port", String(PORT)], {
+    cwd: process.cwd(),
+    stdio: "ignore",
+  });
+
+  for (let attempt = 0; attempt < 50; attempt += 1) {
+    try {
+      const response = await fetch(BASE_URL);
+      if (response.ok) return;
+    } catch {
+      // Vite is still starting.
+    }
+    await delay(100);
+  }
+  throw new Error("Vite did not become ready");
+}
+
+async function installApiFixture(page: Page): Promise<void> {
+  await page.route("**/api/graph/**", async (route) => {
+    const pathname = new URL(route.request().url()).pathname;
+    if (pathname === "/api/graph/stats") {
+      await route.fulfill({ json: { node_count: 4, edge_count: 3 } });
+    } else if (pathname === "/api/graph/nodes") {
+      await route.fulfill({ json: { nodes, total: nodes.length, skip: 0, limit: 1000, next_cursor: null } });
+    } else if (pathname === "/api/graph/edges") {
+      await route.fulfill({ json: { edges, total: edges.length, skip: 0, limit: 1000, next_cursor: null } });
+    } else {
+      await route.continue();
+    }
+  });
+}
+
+test("real Explorer loading path hydrates and renders API edge labels", async (t) => {
+  await startVite();
+  t.after(async () => {
+    server?.kill();
+  });
+
+  const browser = await chromium.launch({
+    headless: true,
+    executablePath: process.env.CHROMIUM_PATH || (existsSync("/usr/bin/chromium") ? "/usr/bin/chromium" : undefined),
+  });
+  t.after(() => browser.close());
+  const page = await browser.newPage({ viewport: { width: 1440, height: 1000 } });
+
+  await page.addInitScript(() => {
+    const captured = (window as Window & { __capturedCanvasText?: string[] }).__capturedCanvasText = [];
+    const originalFillText = CanvasRenderingContext2D.prototype.fillText;
+    CanvasRenderingContext2D.prototype.fillText = function (text: string, ...args: [number, number, number?, number?]) {
+      captured.push(String(text));
+      return originalFillText.call(this, text, ...args);
+    };
+  });
+  await installApiFixture(page);
+  await page.goto(BASE_URL);
+  await page.getByRole("button", { name: /Open Semantica Explorer/ }).click();
+
+  await page.locator("canvas").nth(0).waitFor({ state: "attached" });
+  await page.waitForFunction(() => document.querySelectorAll("canvas").length >= 2);
+  await page.waitForFunction(() => {
+    const labels = (window as Window & { __capturedCanvasText?: string[] }).__capturedCanvasText ?? [];
+    return ["WORKS_AT", "KNOWS", "LOCATED_IN"].every((label) => labels.includes(label));
+  }, undefined, { timeout: 10_000 });
+
+  const capturedLabels = await page.evaluate(() => (window as Window & { __capturedCanvasText?: string[] }).__capturedCanvasText ?? []);
+  for (const label of ["WORKS_AT", "KNOWS", "LOCATED_IN"]) {
+    assert.ok(capturedLabels.includes(label), `Expected rendered edge label ${label}`);
+  }
+  assert.ok(capturedLabels.includes("Alice"));
+
+  await page.getByRole("button", { name: "Zoom In" }).click();
+  await page.waitForTimeout(250);
+  const labelsAfterZoom = await page.evaluate(() => (window as Window & { __capturedCanvasText?: string[] }).__capturedCanvasText ?? []);
+  for (const label of ["WORKS_AT", "KNOWS", "LOCATED_IN"]) {
+    assert.ok(labelsAfterZoom.includes(label), `Expected edge label ${label} after zoom`);
+  }
+});

explorer/tests/deterministicExplorerRendering.test.ts

@@ -0,0 +1,508 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  batchMergeEdges,
+  batchMergeNodes,
+  clearGraph,
+  graph,
+} from "../src/store/graphStore.ts";
+import {
+  buildStructuralDistanceSnapshot,
+  classifyFullGraphEdge,
+  resolveDisplayGraph,
+  resolveEdgeElementStyle,
+  resolveEdgeVisualState,
+  resolveNodeElementStyle,
+  resolveNodeVisualState,
+  shouldForceNodeLabel,
+} from "../src/workspaces/GraphWorkspace/graphSceneState.ts";
+import { GRAPH_THEME, type GraphZoomTier } from "../src/workspaces/GraphWorkspace/graphTheme.ts";
+
+test.beforeEach(() => {
+  clearGraph();
+});
+
+test.after(() => {
+  clearGraph();
+});
+
+/**
+ * Loads the canonical 4-node, 3-edge deterministic test graph (Semantica #1037).
+ *
+ * Graph structure:
+ *   Alice (Person)       --WORKS_AT-->    Acme (Organization)
+ *   Bob (Person)         --KNOWS-->       Alice (Person)
+ *   Acme (Organization)  --LOCATED_IN-->  New York (Location)
+ */
+function loadDeterministicTestGraph() {
+  batchMergeNodes([
+    {
+      id: "alice",
+      attributes: {
+        label: "Alice",
+        content: "Alice",
+        x: 0,
+        y: 0,
+        size: 8,
+        color: "#63E6FF",
+        baseColor: "#63E6FF",
+        nodeType: "Person",
+        semanticGroup: "Person",
+        properties: {},
+      },
+    },
+    {
+      id: "bob",
+      attributes: {
+        label: "Bob",
+        content: "Bob",
+        x: -50,
+        y: 0,
+        size: 8,
+        color: "#63E6FF",
+        baseColor: "#63E6FF",
+        nodeType: "Person",
+        semanticGroup: "Person",
+        properties: {},
+      },
+    },
+    {
+      id: "acme",
+      attributes: {
+        label: "Acme",
+        content: "Acme",
+        x: 50,
+        y: 0,
+        size: 8,
+        color: "#A78BFA",
+        baseColor: "#A78BFA",
+        nodeType: "Organization",
+        semanticGroup: "Organization",
+        properties: {},
+      },
+    },
+    {
+      id: "new_york",
+      attributes: {
+        label: "New York",
+        content: "New York",
+        x: 100,
+        y: 0,
+        size: 8,
+        color: "#34D399",
+        baseColor: "#34D399",
+        nodeType: "Location",
+        semanticGroup: "Location",
+        properties: {},
+      },
+    },
+  ]);
+
+  batchMergeEdges([
+    {
+      id: "edge_alice_acme",
+      source: "alice",
+      target: "acme",
+      attributes: {
+        edgeId: "edge_alice_acme",
+        edgeType: "WORKS_AT",
+        weight: 1.0,
+        visualPriority: 0.8,
+        baseSize: 0.8,
+        properties: {},
+      },
+    },
+    {
+      id: "edge_bob_alice",
+      source: "bob",
+      target: "alice",
+      attributes: {
+        edgeId: "edge_bob_alice",
+        edgeType: "KNOWS",
+        weight: 1.0,
+        visualPriority: 0.8,
+        baseSize: 0.8,
+        properties: {},
+      },
+    },
+    {
+      id: "edge_acme_new_york",
+      source: "acme",
+      target: "new_york",
+      attributes: {
+        edgeId: "edge_acme_new_york",
+        edgeType: "LOCATED_IN",
+        weight: 1.0,
+        visualPriority: 0.8,
+        baseSize: 0.8,
+        properties: {},
+      },
+    },
+  ]);
+}
+
+test("deterministic graph contains exactly 4 nodes and 3 edges in store", () => {
+  loadDeterministicTestGraph();
+
+  assert.equal(graph.order, 4, "Expected exactly 4 nodes");
+  assert.equal(graph.size, 3, "Expected exactly 3 edges");
+
+  // Verify node identities and labels
+  const alice = graph.getNodeAttributes("alice");
+  const bob = graph.getNodeAttributes("bob");
+  const acme = graph.getNodeAttributes("acme");
+  const newYork = graph.getNodeAttributes("new_york");
+
+  assert.equal(alice.label, "Alice");
+  assert.equal(alice.nodeType, "Person");
+  assert.equal(alice.color, "#63E6FF");
+
+  assert.equal(bob.label, "Bob");
+  assert.equal(bob.nodeType, "Person");
+  assert.equal(bob.color, "#63E6FF");
+
+  assert.equal(acme.label, "Acme");
+  assert.equal(acme.nodeType, "Organization");
+  assert.equal(acme.color, "#A78BFA");
+
+  assert.equal(newYork.label, "New York");
+  assert.equal(newYork.nodeType, "Location");
+  assert.equal(newYork.color, "#34D399");
+
+  // Verify edge connectivity and canonical edgeType labels
+  const edgeAliceAcme = graph.getEdgeAttributes("edge_alice_acme");
+  const edgeBobAlice = graph.getEdgeAttributes("edge_bob_alice");
+  const edgeAcmeNewYork = graph.getEdgeAttributes("edge_acme_new_york");
+
+  assert.equal(edgeAliceAcme.edgeType, "WORKS_AT");
+  assert.equal(graph.source("edge_alice_acme"), "alice");
+  assert.equal(graph.target("edge_alice_acme"), "acme");
+
+  assert.equal(edgeBobAlice.edgeType, "KNOWS");
+  assert.equal(graph.source("edge_bob_alice"), "bob");
+  assert.equal(graph.target("edge_bob_alice"), "alice");
+
+  assert.equal(edgeAcmeNewYork.edgeType, "LOCATED_IN");
+  assert.equal(graph.source("edge_acme_new_york"), "acme");
+  assert.equal(graph.target("edge_acme_new_york"), "new_york");
+});
+
+test("display graph resolution preserves all 4 nodes and 3 edges in full view", () => {
+  loadDeterministicTestGraph();
+
+  const { graph: displayGraph } = resolveDisplayGraph("", [], [], "full", { aggregationEnabled: false });
+
+  assert.equal(displayGraph.order, 4);
+  assert.equal(displayGraph.size, 3);
+  assert.ok(displayGraph.hasNode("alice"));
+  assert.ok(displayGraph.hasNode("bob"));
+  assert.ok(displayGraph.hasNode("acme"));
+  assert.ok(displayGraph.hasNode("new_york"));
+  assert.ok(displayGraph.hasEdge("edge_alice_acme"));
+  assert.ok(displayGraph.hasEdge("edge_bob_alice"));
+  assert.ok(displayGraph.hasEdge("edge_acme_new_york"));
+});
+
+test("structural distance calculation resolves correct hop counts across the 3-edge chain", () => {
+  loadDeterministicTestGraph();
+
+  // From Bob: Bob (0) -> Alice (1) -> Acme (2) -> New York (3)
+  const distances = buildStructuralDistanceSnapshot(graph, "bob", 3);
+
+  assert.equal(distances.bob, 0);
+  assert.equal(distances.alice, 1);
+  assert.equal(distances.acme, 2);
+  assert.equal(distances.new_york, 3);
+});
+
+test("edge rendering and canonical edge labels remain legible across zoom tiers and inspection modes", () => {
+  loadDeterministicTestGraph();
+
+  const canonicalEdges = [
+    { id: "edge_alice_acme", source: "alice", target: "acme", label: "WORKS_AT" },
+    { id: "edge_bob_alice", source: "bob", target: "alice", label: "KNOWS" },
+    { id: "edge_acme_new_york", source: "acme", target: "new_york", label: "LOCATED_IN" },
+  ];
+
+  // 1. Edge attributes preserve canonical edgeType labels in graph store:
+  for (const item of canonicalEdges) {
+    const attrs = graph.getEdgeAttributes(item.id);
+    assert.equal(attrs.edgeType, item.label, `Edge ${item.id} must have edgeType ${item.label}`);
+    assert.equal(graph.source(item.id), item.source);
+    assert.equal(graph.target(item.id), item.target);
+  }
+
+  // 2. In active context / neighbor state across all zoom tiers (overview, structure, inspection):
+  const allTiers: GraphZoomTier[] = ["overview", "structure", "inspection"];
+  for (const tier of allTiers) {
+    for (const item of canonicalEdges) {
+      const attrs = graph.getEdgeAttributes(item.id);
+      const contextStyle = resolveEdgeElementStyle(
+        GRAPH_THEME,
+        tier,
+        "neighbor",
+        attrs,
+        item.source,
+        item.target,
+        "full",
+        item.id,
+      );
+
+      assert.equal(
+        contextStyle.hidden,
+        false,
+        `Edge ${item.id} (${item.label}) in context state 'neighbor' must be visible in zoom tier '${tier}'`,
+      );
+      assert.ok(
+        contextStyle.size !== undefined && contextStyle.size > 0,
+        `Edge ${item.id} (${item.label}) must have positive render size in zoom tier '${tier}'`,
+      );
+    }
+  }
+
+  // 3. In selected state in inspection zoom tier (close examination of edge details and label):
+  for (const item of canonicalEdges) {
+    const attrs = graph.getEdgeAttributes(item.id);
+    const selectedStyle = resolveEdgeElementStyle(
+      GRAPH_THEME,
+      "inspection",
+      "selected",
+      attrs,
+      item.source,
+      item.target,
+      "full",
+      item.id,
+      "selected",
+    );
+
+    assert.equal(
+      selectedStyle.hidden,
+      false,
+      `Selected edge ${item.id} (${item.label}) must be visible in inspection zoom tier`,
+    );
+    assert.ok(
+      selectedStyle.size !== undefined && selectedStyle.size > 0,
+      `Selected edge ${item.id} (${item.label}) must have positive render size`,
+    );
+  }
+
+  // 4. Verify inspection zoom tier camera and arrow rendering settings
+  assert.equal(GRAPH_THEME.zoomTiers.inspection.showContextualArrows, true);
+  assert.equal(GRAPH_THEME.zoomTiers.inspection.showCurves, true);
+});
+
+test("node hover interaction preserves edge visibility and highlights canonical incident edge types", () => {
+  loadDeterministicTestGraph();
+
+  // Scenario 1: Hover Alice
+  // Incident edges: Alice -> Acme (WORKS_AT) and Bob -> Alice (KNOWS)
+  const aliceAttrs = graph.getNodeAttributes("alice");
+  const aliceVisual = resolveNodeVisualState("alice", "structure", "alice", "", "", new Set(), new Set(), new Set());
+  assert.equal(aliceVisual, "hovered");
+
+  const aliceStyle = resolveNodeElementStyle(GRAPH_THEME, "structure", "hovered", aliceAttrs, "Alice");
+  assert.equal(aliceStyle.forceLabel, true, "Hovered Alice must force-render label");
+  assert.equal(aliceStyle.label, "Alice");
+  assert.equal(aliceStyle.showHalo, true, "Hovered Alice must show interactive halo");
+
+  const aliceIncidentEdges = new Set(["edge_alice_acme", "edge_bob_alice"]);
+
+  // Edge Alice -> Acme (WORKS_AT) under Alice hover
+  const aliceAcmeAttrs = graph.getEdgeAttributes("edge_alice_acme");
+  assert.equal(aliceAcmeAttrs.edgeType, "WORKS_AT");
+  const aliceAcmeState = resolveEdgeVisualState(
+    "edge_alice_acme",
+    "alice",
+    "acme",
+    "structure",
+    "alice",
+    "",
+    "",
+    new Set(),
+    new Set(),
+    aliceIncidentEdges,
+  );
+  assert.equal(aliceAcmeState, "hovered");
+  const aliceAcmeStyle = resolveEdgeElementStyle(
+    GRAPH_THEME,
+    "structure",
+    "hovered",
+    aliceAcmeAttrs,
+    "alice",
+    "acme",
+    "full",
+    "edge_alice_acme",
+  );
+  assert.equal(aliceAcmeStyle.hidden, false, "Incident edge WORKS_AT must remain visible on hover");
+  assert.ok(aliceAcmeStyle.size !== undefined && aliceAcmeStyle.size > 0);
+
+  // Edge Bob -> Alice (KNOWS) under Alice hover
+  const bobAliceAttrs = graph.getEdgeAttributes("edge_bob_alice");
+  assert.equal(bobAliceAttrs.edgeType, "KNOWS");
+  const bobAliceState = resolveEdgeVisualState(
+    "edge_bob_alice",
+    "bob",
+    "alice",
+    "structure",
+    "alice",
+    "",
+    "",
+    new Set(),
+    new Set(),
+    aliceIncidentEdges,
+  );
+  assert.equal(bobAliceState, "hovered");
+  const bobAliceStyle = resolveEdgeElementStyle(
+    GRAPH_THEME,
+    "structure",
+    "hovered",
+    bobAliceAttrs,
+    "bob",
+    "alice",
+    "full",
+    "edge_bob_alice",
+  );
+  assert.equal(bobAliceStyle.hidden, false, "Incident edge KNOWS must remain visible on hover");
+
+  // Non-incident edge Acme -> New York (LOCATED_IN) under Alice hover
+  const acmeNyAttrs = graph.getEdgeAttributes("edge_acme_new_york");
+  assert.equal(acmeNyAttrs.edgeType, "LOCATED_IN");
+  const acmeNyState = resolveEdgeVisualState(
+    "edge_acme_new_york",
+    "acme",
+    "new_york",
+    "structure",
+    "alice",
+    "",
+    "",
+    new Set(),
+    new Set(),
+    aliceIncidentEdges,
+  );
+  assert.equal(acmeNyState, "muted");
+
+  // Scenario 2: Hover Acme
+  // Incident edges: Alice -> Acme (WORKS_AT) and Acme -> New York (LOCATED_IN)
+  const acmeAttrs = graph.getNodeAttributes("acme");
+  const acmeStyle = resolveNodeElementStyle(GRAPH_THEME, "structure", "hovered", acmeAttrs, "Acme");
+  assert.equal(acmeStyle.forceLabel, true);
+  assert.equal(acmeStyle.label, "Acme");
+
+  const acmeIncidentEdges = new Set(["edge_alice_acme", "edge_acme_new_york"]);
+  const acmeNyHoverState = resolveEdgeVisualState(
+    "edge_acme_new_york",
+    "acme",
+    "new_york",
+    "structure",
+    "acme",
+    "",
+    "",
+    new Set(),
+    new Set(),
+    acmeIncidentEdges,
+  );
+  assert.equal(acmeNyHoverState, "hovered");
+  const acmeNyHoverStyle = resolveEdgeElementStyle(
+    GRAPH_THEME,
+    "structure",
+    "hovered",
+    acmeNyAttrs,
+    "acme",
+    "new_york",
+    "full",
+    "edge_acme_new_york",
+  );
+  assert.equal(acmeNyHoverStyle.hidden, false, "Incident edge LOCATED_IN must remain visible on hover");
+
+  // Scenario 3: Hover Bob
+  // Incident edge: Bob -> Alice (KNOWS)
+  const bobAttrs = graph.getNodeAttributes("bob");
+  const bobStyle = resolveNodeElementStyle(GRAPH_THEME, "structure", "hovered", bobAttrs, "Bob");
+  assert.equal(bobStyle.forceLabel, true);
+  assert.equal(bobStyle.label, "Bob");
+
+  const bobIncidentEdges = new Set(["edge_bob_alice"]);
+  const bobAliceHoverState = resolveEdgeVisualState(
+    "edge_bob_alice",
+    "bob",
+    "alice",
+    "structure",
+    "bob",
+    "",
+    "",
+    new Set(),
+    new Set(),
+    bobIncidentEdges,
+  );
+  assert.equal(bobAliceHoverState, "hovered");
+});
+
+test("edge selection maintains canonical edge type labels and active visual state", () => {
+  loadDeterministicTestGraph();
+
+  const edgeCases = [
+    { id: "edge_alice_acme", source: "alice", target: "acme", label: "WORKS_AT" },
+    { id: "edge_bob_alice", source: "bob", target: "alice", label: "KNOWS" },
+    { id: "edge_acme_new_york", source: "acme", target: "new_york", label: "LOCATED_IN" },
+  ];
+
+  for (const { id, source, target, label } of edgeCases) {
+    const attrs = graph.getEdgeAttributes(id);
+    assert.equal(attrs.edgeType, label);
+
+    const visualState = resolveEdgeVisualState(
+      id,
+      source,
+      target,
+      "inspection",
+      null,
+      "",
+      id, // selected edge
+      new Set(),
+      new Set(),
+    );
+    assert.equal(visualState, "selected", `Selected edge ${id} must resolve to 'selected' state`);
+
+    const style = resolveEdgeElementStyle(
+      GRAPH_THEME,
+      "inspection",
+      "selected",
+      attrs,
+      source,
+      target,
+      "full",
+      id,
+      "selected",
+    );
+
+    assert.equal(style.hidden, false, `Selected edge ${id} (${label}) must not be hidden`);
+    assert.ok(
+      style.size !== undefined && style.size > 0,
+      `Selected edge ${id} (${label}) must have positive render size`,
+    );
+  }
+});
+
+test("node labels remain forced visible during hover, selection, and inspection zoom tier", () => {
+  loadDeterministicTestGraph();
+
+  const nodes = ["alice", "bob", "acme", "new_york"];
+
+  for (const nid of nodes) {
+    const attrs = graph.getNodeAttributes(nid);
+
+    // Hover state forces label visibility
+    const hoverForcesLabel = shouldForceNodeLabel(GRAPH_THEME, "structure", "hovered", attrs, 0);
+    assert.equal(hoverForcesLabel, true, `Node ${nid} label must force visible on hover`);
+
+    // Selected state forces label visibility
+    const selectForcesLabel = shouldForceNodeLabel(GRAPH_THEME, "structure", "selected", attrs, 0);
+    assert.equal(selectForcesLabel, true, `Node ${nid} label must force visible on selection`);
+
+    // Resolved style emits actual string label
+    const style = resolveNodeElementStyle(GRAPH_THEME, "inspection", "hovered", attrs, attrs.label);
+    assert.equal(style.forceLabel, true);
+    assert.equal(style.label, attrs.label);
+  }
+});

explorer/tests/markdownContentViewer.test.ts

@@ -5,7 +5,8 @@ import { renderToString } from "react-dom/server";
 
 (globalThis as any).React = React;
 
-import { isSafeUrl, MarkdownContentViewer } from "../src/workspaces/GraphWorkspace/MarkdownContentViewer.tsx";
+import { MarkdownContentViewer } from "../src/workspaces/GraphWorkspace/MarkdownContentViewer.tsx";
+import { isSafeUrl } from "../src/workspaces/GraphWorkspace/markdownUrlSafety.ts";
 
 test("isSafeUrl permits safe http, https, and mailto URLs and relative paths", () => {
   assert.equal(isSafeUrl("https://example.com"), true);

explorer/tests/temporalSnapshotGuards.test.ts

@@ -0,0 +1,150 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { createTemporalSnapshotGuards } from "../src/workspaces/GraphWorkspace/temporalSnapshotGuards.ts";
+
+const POSITION_1 = new Date("2023-07-02T00:00:00Z").getTime();
+const POSITION_2 = new Date("2024-01-02T00:00:00Z").getTime();
+const POSITION_3 = new Date("2024-07-02T00:00:00Z").getTime();
+
+const SNAPSHOT = { active_node_ids: ["n1", "n2"], active_node_count: 2 };
+
+// ── begin: one request per scrubber position ─────────────────────────────────
+
+test("begin: a new position returns a fresh request sequence", () => {
+  const guards = createTemporalSnapshotGuards();
+  assert.deepEqual(guards.begin(POSITION_1), { seq: 1, cached: null });
+});
+
+test("begin: an identical in-flight request is deduplicated (no duplicate fetch)", () => {
+  const guards = createTemporalSnapshotGuards();
+  guards.begin(POSITION_1);
+  assert.deepEqual(guards.begin(POSITION_1), { seq: null, cached: null });
+});
+
+test("begin: distinct positions request independently", () => {
+  const guards = createTemporalSnapshotGuards();
+  assert.equal(guards.begin(POSITION_1).seq, 1);
+  assert.equal(guards.begin(POSITION_2).seq, 2);
+});
+
+test("begin: revisiting an applied position returns its cached snapshot", () => {
+  const guards = createTemporalSnapshotGuards();
+  const { seq } = guards.begin(POSITION_1);
+  guards.apply(POSITION_1, seq, SNAPSHOT);
+  const revisit = guards.begin(POSITION_1);
+  assert.equal(revisit.seq, 2);
+  assert.deepEqual(revisit.cached, SNAPSHOT);
+});
+
+test("begin: a failed position (finished) can be requested again", () => {
+  const guards = createTemporalSnapshotGuards();
+  const { seq } = guards.begin(POSITION_1);
+  guards.finish(POSITION_1, seq);
+  const retry = guards.begin(POSITION_1);
+  assert.equal(retry.seq, 2);
+  assert.equal(retry.cached, null);
+});
+
+test("finish: does not clear a position whose snapshot was already applied", () => {
+  const guards = createTemporalSnapshotGuards();
+  const { seq } = guards.begin(POSITION_1);
+  guards.apply(POSITION_1, seq, SNAPSHOT);
+  guards.finish(POSITION_1, seq);
+  assert.deepEqual(guards.begin(POSITION_1).cached, SNAPSHOT);
+});
+
+test("finish: a stale sequence cannot release a newer request's position", () => {
+  const guards = createTemporalSnapshotGuards();
+  const first = guards.begin(POSITION_1);
+  guards.finish(POSITION_1, first.seq);
+  guards.begin(POSITION_1); // seq 2, in flight again
+  guards.finish(POSITION_1, first.seq); // stale seq: must not release seq 2
+  assert.deepEqual(guards.begin(POSITION_1), { seq: null, cached: null });
+});
+
+// ── shouldApply: applied only while the scrubber is on that position ─────────
+
+test("shouldApply: the current position's response is applied", () => {
+  const guards = createTemporalSnapshotGuards();
+  const { seq } = guards.begin(POSITION_1);
+  assert.equal(guards.shouldApply(POSITION_1, seq), true);
+});
+
+test("shouldApply: a response for a position the scrubber left is discarded", () => {
+  const guards = createTemporalSnapshotGuards();
+  const { seq: seq1 } = guards.begin(POSITION_1);
+  guards.begin(POSITION_2);
+  assert.equal(guards.shouldApply(POSITION_1, seq1), false);
+  assert.equal(guards.shouldApply(POSITION_2, 2), true);
+});
+
+test("shouldApply: a late response for the position the scrubber returned to is applied", () => {
+  const guards = createTemporalSnapshotGuards();
+  const { seq: seq1 } = guards.begin(POSITION_1);
+  const { seq: seq2 } = guards.begin(POSITION_2);
+  guards.begin(POSITION_1); // back to 1: deduplicated, no new request
+  assert.equal(guards.shouldApply(POSITION_1, seq1), true);
+  assert.equal(guards.shouldApply(POSITION_2, seq2), false);
+});
+
+test("shouldApply: an unknown sequence is discarded", () => {
+  const guards = createTemporalSnapshotGuards();
+  guards.begin(POSITION_1);
+  assert.equal(guards.shouldApply(POSITION_1, 99), false);
+});
+
+test("shouldApply: after a reset no pre-reset response applies", () => {
+  const guards = createTemporalSnapshotGuards();
+  const { seq } = guards.begin(POSITION_1);
+  guards.reset();
+  assert.equal(guards.shouldApply(POSITION_1, seq), false);
+});
+
+// ── apply: caching for revisits ─────────────────────────────────────────────
+
+test("apply: stores the snapshot so a revisit re-applies it without a request", () => {
+  const guards = createTemporalSnapshotGuards();
+  const { seq } = guards.begin(POSITION_1);
+  guards.apply(POSITION_1, seq, SNAPSHOT);
+  guards.begin(POSITION_2);
+  assert.deepEqual(guards.begin(POSITION_1).cached, SNAPSHOT);
+});
+
+test("apply: play wrap-around re-applies the wrapped-to position's snapshot", () => {
+  const guards = createTemporalSnapshotGuards();
+  const { seq } = guards.begin(POSITION_1);
+  guards.apply(POSITION_1, seq, SNAPSHOT);
+  guards.begin(POSITION_2);
+  guards.begin(POSITION_3);
+  const wrap = guards.begin(POSITION_1);
+  assert.deepEqual(wrap.cached, SNAPSHOT);
+  assert.equal(guards.shouldApply(POSITION_1, wrap.seq), true);
+});
+
+// ── reset: graph reload ─────────────────────────────────────────────────────
+
+test("reset: clears requested and cached state so positions refetch", () => {
+  const guards = createTemporalSnapshotGuards();
+  const { seq } = guards.begin(POSITION_1);
+  guards.apply(POSITION_1, seq, SNAPSHOT);
+  guards.reset();
+  const fresh = guards.begin(POSITION_1);
+  assert.equal(fresh.seq, 1);
+  assert.equal(fresh.cached, null);
+});
+
+// ── cache bound ─────────────────────────────────────────────────────────────
+
+test("cache: oldest positions are evicted when the cache is full", () => {
+  const guards = createTemporalSnapshotGuards();
+  const count = 300;
+  for (let i = 0; i < count; i++) {
+    const { seq } = guards.begin(POSITION_1 + i * 1000);
+    guards.apply(POSITION_1 + i * 1000, seq, SNAPSHOT);
+  }
+  const oldest = guards.begin(POSITION_1);
+  assert.equal(oldest.cached, null); // evicted: must refetch on revisit
+  const newest = guards.begin(POSITION_1 + (count - 1) * 1000);
+  assert.deepEqual(newest.cached, SNAPSHOT); // still cached
+});

integrations/__init__.py

@@ -1,7 +1,7 @@
 """
 Semantica Framework Integrations
 
-Optional integration packages for agentic frameworks (Google ADK, Claude Agent SDK, Agno, etc.).
+Optional integration packages for agentic frameworks (Google ADK, Claude Agent SDK, Agno, CrewAI, LangChain, etc.).
 Each integration is self-contained, independently installable via extras_require, and maintains
 zero impact on core Semantica - keeping the semantic layer lean while maximizing ecosystem reach.
 """

integrations/agno/knowledge_graph.py

@@ -277,25 +277,22 @@ class AgnoKnowledgeGraph(_KnowledgeBase):  # type: ignore[misc]
     def load_urls(self, urls: List[str]) -> None:
         """Fetch each URL and ingest the response body.
 
-        Only ``http`` and ``https`` schemes are permitted to prevent SSRF.
+        Uses the shared SSRF guard so that ``http`` and ``https`` are the only
+        permitted schemes, private/loopback/link-local/cloud-metadata addresses
+        are blocked by default, DNS resolution is validated, and every redirect
+        hop is re-checked before being followed.
         """
-        import urllib.request
-        from urllib.parse import urlparse
+        from semantica.ingest.ssrf import request_with_ssrf_guard
+        from semantica.utils.exceptions import ValidationError
 
         for url in urls:
-            parsed = urlparse(url)
-            if parsed.scheme not in ("http", "https"):
-                logger.warning(
-                    "Skipping URL with disallowed scheme '%s': %s",
-                    parsed.scheme,
-                    url,
-                )
-                continue
             try:
-                with urllib.request.urlopen(url, timeout=10) as resp:  # noqa: S310
-                    text = resp.read().decode("utf-8", errors="replace")
+                response = request_with_ssrf_guard("GET", url, timeout=10)
+                text = response.text
                 self._ingest_text(text, source=url)
                 logger.info("Loaded URL: %s", url)
+            except ValidationError as exc:
+                logger.warning("Skipping URL (SSRF check failed) %s: %s", url, exc)
             except Exception as exc:
                 logger.warning("Failed to fetch %s: %s", url, exc)
 

integrations/langchain/README.md

@@ -0,0 +1,67 @@
+# Semantica × LangChain
+
+Drop Semantica into existing LangChain / LangGraph pipelines: GraphRAG-style
+retrieval, a `VectorStore` adapter, and agent tools.
+
+## Install
+
+```bash
+pip install semantica[langchain]
+# or just the core adapter dependency:
+pip install langchain-core
+```
+
+## Retriever (GraphRAG)
+
+```python
+from integrations.langchain import SemanticaRetriever
+from semantica.context import ContextGraph
+from semantica.vector_store import HybridSearch
+
+graph = ContextGraph()
+hybrid = HybridSearch()
+
+retriever = SemanticaRetriever(graph=graph, hybrid=hybrid, hops=2, top_k=10)
+
+# Use with any LangChain chain that accepts a retriever:
+from langchain.chains import RetrievalQA
+
+qa = RetrievalQA.from_chain_type(llm=llm, retriever=retriever)
+```
+
+Hybrid search seeds retrieval; then graph edges are walked `hops` steps so
+results go beyond flat vector similarity.
+
+## VectorStore
+
+```python
+from integrations.langchain import SemanticaVectorStore
+
+store = SemanticaVectorStore(hybrid=hybrid)
+store.add_texts(["document one", "document two"], metadatas=[{"source": "a"}, {"source": "b"}])
+docs = store.similarity_search("document", k=2)
+docs, scores = store.similarity_search_with_score("document", k=2)
+```
+
+## Agent tools (LangGraph / tool-calling agents)
+
+```python
+from integrations.langchain import SemanticaKGTool, SemanticaDecisionTool
+from langgraph.prebuilt import create_react_agent
+
+tools = [
+    SemanticaKGTool(graph),
+    SemanticaDecisionTool(graph),
+]
+agent = create_react_agent(model, tools)
+```
+
+- `semantica_query_graph` — query the shared context graph (keyword / NL)
+- `semantica_query_decisions` — search the recorded decision log
+
+## Compatibility
+
+- Requires `langchain-core >= 0.3`.
+- All classes degrade gracefully when `langchain-core` is absent: they remain
+  importable (carrying the full Semantica API), and `build()` returns `None`,
+  so agents can branch on `LANGCHAIN_AVAILABLE`.

integrations/langchain/__init__.py

@@ -0,0 +1,48 @@
+"""
+Semantica × LangChain Integration
+=================================
+
+First-class integration between the Semantica semantic intelligence stack and
+the `LangChain <https://github.com/langchain-ai/langchain>`_ / LangGraph
+ecosystem.
+
+Public surface
+--------------
+SemanticaRetriever  — ``BaseRetriever`` with multi-hop GraphRAG (walks graph
+                      edges from hybrid-search hits)
+SemanticaVectorStore — ``VectorStore`` adapter over Semantica's hybrid search
+                      (drop-in for RetrievalQA / LCEL chains)
+SemanticaKGTool     — ``BaseTool`` for querying the context graph
+SemanticaDecisionTool — ``BaseTool`` exposing the recorded decision log
+
+Quick start
+-----------
+    pip install semantica[langchain]
+
+    >>> from integrations.langchain import (
+    ...     SemanticaRetriever,
+    ...     SemanticaVectorStore,
+    ...     SemanticaKGTool,
+    ...     SemanticaDecisionTool,
+    ... )
+
+Compatibility
+-------------
+Requires ``langchain-core >= 0.3``. All classes degrade gracefully when
+``langchain-core`` is not installed — they are still importable and carry the
+full Semantica API, but cannot be bound to LangChain chains/agents.
+"""
+
+from .retriever import LANGCHAIN_AVAILABLE, SemanticaRetriever
+from .tools import SemanticaDecisionTool, SemanticaKGTool
+from .vectorstore import SemanticaVectorStore
+
+__all__ = [
+    "SemanticaRetriever",
+    "SemanticaVectorStore",
+    "SemanticaKGTool",
+    "SemanticaDecisionTool",
+    "LANGCHAIN_AVAILABLE",
+]
+
+__version__ = "0.1.0"

integrations/langchain/retriever.py

@@ -0,0 +1,216 @@
+"""
+SemanticaRetriever — LangChain ``BaseRetriever`` with multi-hop GraphRAG.
+
+Hybrid search seeds the retrieval, then graph edges are walked for ``hops``
+steps so results go beyond flat vector similarity.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+from semantica.utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+# ---------------------------------------------------------------------------
+# Optional: LangChain core
+# ---------------------------------------------------------------------------
+LANGCHAIN_AVAILABLE = False
+LANGCHAIN_IMPORT_ERROR: Optional[str] = None
+
+_BaseRetriever: Any = object
+_Document: Any = None
+
+
+def _get_document(**kwargs: Any) -> Any:
+    """Instantiate a langchain Document lazily (keeps the import optional)."""
+    if _Document is None:  # pragma: no cover - exercised only with langchain
+        raise RuntimeError(LANGCHAIN_IMPORT_ERROR or "langchain-core not installed")
+    return _Document(**kwargs)
+
+
+try:
+    from langchain_core.documents import Document as _Document  # type: ignore
+    from langchain_core.retrievers import (
+        BaseRetriever as _BaseRetriever,  # type: ignore
+    )
+
+    LANGCHAIN_AVAILABLE = True
+except ImportError:  # pragma: no cover - exercised only without langchain
+    LANGCHAIN_IMPORT_ERROR = (
+        "langchain-core is not installed. Install with: pip install langchain-core"
+    )
+    logger.debug(LANGCHAIN_IMPORT_ERROR)
+
+
+def _hit_layers(hit: Dict[str, Any]) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    """Nested HybridSearch metadata and ContextGraph.query node, if present."""
+    metadata = hit.get("metadata") if isinstance(hit.get("metadata"), dict) else {}
+    node = hit.get("node") if isinstance(hit.get("node"), dict) else {}
+    return metadata, node
+
+
+def _hit_id(hit: Dict[str, Any]) -> Optional[str]:
+    """Graph node id, preferring metadata over a HybridSearch vector id."""
+    metadata, node = _hit_layers(hit)
+    return (
+        hit.get("node_id")
+        or metadata.get("node_id")
+        or node.get("id")
+        or node.get("node_id")
+        or hit.get("id")
+    )
+
+
+def _hit_content(hit: Dict[str, Any], fallback: str = "") -> str:
+    metadata, node = _hit_layers(hit)
+    props = node.get("properties") if isinstance(node.get("properties"), dict) else {}
+    return (
+        hit.get("content")
+        or hit.get("text")
+        or metadata.get("content")
+        or metadata.get("text")
+        or props.get("content")
+        or fallback
+    )
+
+
+def _hit_type(hit: Dict[str, Any]) -> str:
+    metadata, node = _hit_layers(hit)
+    return (
+        hit.get("node_type")
+        or hit.get("type")
+        or metadata.get("node_type")
+        or metadata.get("type")
+        or node.get("type")
+        or node.get("node_type")
+        or "node"
+    )
+
+
+def _hit_score(hit: Dict[str, Any], default: float = 1.0) -> float:
+    return float(hit.get("score") if hit.get("score") is not None else hit.get("distance") or default)
+
+
+class SemanticaRetriever(_BaseRetriever):  # type: ignore[misc]
+    """GraphRAG-style retriever over a Semantica ``ContextGraph``.
+
+    Args:
+        graph: A semantica.context.ContextGraph instance.
+        hybrid: A semantica.vector_store.HybridSearch instance used to seed
+            retrieval. If omitted, a best-effort keyword search on the graph
+            is used.
+        hops: Number of graph-edge expansion hops (default 2).
+        top_k: Number of seed hits (default 10).
+    """
+
+    graph: Any
+    hybrid: Any = None
+    hops: int = 2
+    top_k: int = 10
+
+    def __init__(
+        self,
+        graph: Any,
+        hybrid: Any = None,
+        hops: int = 2,
+        top_k: int = 10,
+        **kwargs: Any,
+    ) -> None:
+        """Explicit init so the retriever works with and without langchain."""
+        if LANGCHAIN_AVAILABLE:
+            # BaseRetriever is a Pydantic model: pass the declared fields
+            # through so validation succeeds.
+            super().__init__(
+                graph=graph,
+                hybrid=hybrid,
+                hops=hops,
+                top_k=top_k,
+                **kwargs,
+            )
+        else:
+            # Without langchain-core, BaseRetriever is a plain object
+            super().__init__()  # type: ignore[call-arg]
+            self.graph = graph
+            self.hybrid = hybrid
+            self.hops = hops
+            self.top_k = top_k
+
+    def _get_relevant_documents(self, query: str, **kwargs: Any) -> List[Any]:
+        """LangChain BaseRetriever entry point."""
+        seed = self._seed_results(query)
+        if not seed:
+            return []
+
+        # Expand each seed node through the graph
+        expanded: Dict[str, Dict[str, Any]] = {}
+        for hit in seed:
+            node_id = _hit_id(hit)
+            if not node_id:
+                continue
+            metadata, _ = _hit_layers(hit)
+            expanded[node_id] = {
+                "content": _hit_content(hit, fallback=str(node_id)),
+                "node_type": _hit_type(hit),
+                "score": _hit_score(hit),
+                "metadata": metadata,
+            }
+            try:
+                neighbors = self.graph.get_neighbors(node_id, hops=self.hops)
+                for neighbor in neighbors:
+                    nid = neighbor.get("node_id") or neighbor.get("id")
+                    if nid and nid not in expanded:
+                        expanded[nid] = {
+                            "content": neighbor.get("content")
+                            or neighbor.get("text")
+                            or neighbor.get("name")
+                            or str(nid),
+                            "node_type": neighbor.get("node_type")
+                            or neighbor.get("type")
+                            or "node",
+                            "score": float(neighbor.get("weight") or 0.5),
+                            "metadata": {},
+                        }
+            except Exception as exc:  # graph expansion is best-effort
+                logger.debug("graph expansion failed for %s: %s", node_id, exc)
+
+        # Order: seed hits first (they have real scores), then neighbors.
+        # Keep a deterministic id->payload list (sets are unordered — see Qodo).
+        ordered_pairs: List[tuple] = []
+        seen_ids = set()
+        for hit in seed:
+            nid = _hit_id(hit)
+            if nid and nid in expanded and nid not in seen_ids:
+                ordered_pairs.append((nid, expanded[nid]))
+                seen_ids.add(nid)
+        for nid, item in expanded.items():
+            if nid not in seen_ids:
+                ordered_pairs.append((nid, item))
+                seen_ids.add(nid)
+
+        return [
+            _get_document(
+                page_content=item["content"],
+                metadata={
+                    **item["metadata"],
+                    "node_id": nid,
+                    "node_type": item["node_type"],
+                    "score": item["score"],
+                },
+            )
+            for nid, item in ordered_pairs
+        ]
+
+    def _seed_results(self, query: str) -> List[Dict[str, Any]]:
+        """Get seed results from hybrid search or a graph keyword scan."""
+        if self.hybrid is not None:
+            try:
+                return self.hybrid.search(query, k=self.top_k)
+            except Exception as exc:
+                logger.debug("hybrid search failed, falling back: %s", exc)
+        # Best-effort keyword scan over graph nodes (ContextGraph.query)
+        try:
+            return self.graph.query(query, limit=self.top_k)
+        except Exception:
+            return []

integrations/langchain/tools.py

@@ -0,0 +1,133 @@
+"""
+SemanticaKGTool / SemanticaDecisionTool — LangChain ``BaseTool`` adapters
+for LangChain / LangGraph agents.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional, Type
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from semantica.utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+# ---------------------------------------------------------------------------
+# Optional: LangChain core
+# ---------------------------------------------------------------------------
+LANGCHAIN_AVAILABLE = False
+LANGCHAIN_IMPORT_ERROR: Optional[str] = None
+
+_BaseTool: Any = object
+
+
+try:
+    from langchain_core.tools import BaseTool as _BaseTool  # type: ignore
+
+    LANGCHAIN_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    LANGCHAIN_IMPORT_ERROR = (
+        "langchain-core is not installed. Install with: pip install langchain-core"
+    )
+    logger.debug(LANGCHAIN_IMPORT_ERROR)
+
+
+def _json(payload: Any) -> str:
+    return json.dumps(payload, default=str, ensure_ascii=False)
+
+
+class QueryGraphInput(BaseModel):
+    query: str = Field(..., description="Natural-language or keyword graph query")
+    limit: int = Field(10, description="Maximum matching nodes to return")
+
+
+class QueryDecisionsInput(BaseModel):
+    category: str = Field(
+        "",
+        description="Keyword to search recorded decisions; empty returns insights",
+    )
+    limit: int = Field(10, description="Maximum results when searching by keyword")
+
+
+class SemanticaKGTool(_BaseTool):  # type: ignore[misc]
+    """LangChain tool for querying a Semantica ``ContextGraph``.
+
+    Args:
+        graph: A semantica.context.ContextGraph instance.
+
+    Example:
+        >>> tool = SemanticaKGTool(graph)
+        >>> agent = create_react_agent(model, tools=[tool])
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    name: str = "semantica_query_graph"
+    description: str = (
+        "Query Semantica's shared context graph with a natural-language "
+        "keyword query. Returns matching entities and relationships."
+    )
+    args_schema: Type[BaseModel] = QueryGraphInput
+    graph: Any = None
+
+    def __init__(self, graph: Any = None, **kwargs: Any) -> None:
+        if LANGCHAIN_AVAILABLE:
+            super().__init__(graph=graph, **kwargs)
+        else:
+            super().__init__()
+            self.graph = graph
+
+    def build(self) -> Any:
+        """Return this tool, or None if langchain-core is missing."""
+        return self if LANGCHAIN_AVAILABLE else None
+
+    def _run(self, query: str, limit: int = 10, **kwargs: Any) -> str:
+        try:
+            return _json(self.graph.query(query, limit=limit))
+        except Exception as exc:
+            return _json({"error": str(exc)})
+
+    async def _arun(self, query: str, limit: int = 10, **kwargs: Any) -> str:
+        return self._run(query, limit=limit)
+
+
+class SemanticaDecisionTool(_BaseTool):  # type: ignore[misc]
+    """LangChain tool for searching Semantica's recorded decision log.
+
+    Args:
+        graph: A semantica.context.ContextGraph instance.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    name: str = "semantica_query_decisions"
+    description: str = (
+        "Search Semantica's recorded decision log with a keyword query. "
+        "Returns decisions, rationale, and context."
+    )
+    args_schema: Type[BaseModel] = QueryDecisionsInput
+    graph: Any = None
+
+    def __init__(self, graph: Any = None, **kwargs: Any) -> None:
+        if LANGCHAIN_AVAILABLE:
+            super().__init__(graph=graph, **kwargs)
+        else:
+            super().__init__()
+            self.graph = graph
+
+    def build(self) -> Any:
+        """Return this tool, or None if langchain-core is missing."""
+        return self if LANGCHAIN_AVAILABLE else None
+
+    def _run(self, category: str = "", limit: int = 10, **kwargs: Any) -> str:
+        try:
+            if category:
+                return _json(self.graph.query(category, limit=limit))
+            return _json(self.graph.get_decision_insights())
+        except Exception as exc:
+            return _json({"error": str(exc)})
+
+    async def _arun(self, category: str = "", limit: int = 10, **kwargs: Any) -> str:
+        return self._run(category=category, limit=limit)

integrations/langchain/vectorstore.py

@@ -0,0 +1,143 @@
+"""
+SemanticaVectorStore — LangChain ``VectorStore`` adapter over Semantica's
+hybrid search (``semantica.vector_store.HybridSearch``).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Optional
+
+from semantica.utils.logging import get_logger
+
+from .retriever import _hit_content, _hit_id, _hit_score, _hit_type, _hit_layers
+
+logger = get_logger(__name__)
+
+# ---------------------------------------------------------------------------
+# Optional: LangChain core
+# ---------------------------------------------------------------------------
+LANGCHAIN_AVAILABLE = False
+LANGCHAIN_IMPORT_ERROR: Optional[str] = None
+
+_VectorStoreBase: Any = object
+_Document: Any = None
+
+
+def _make_document(**kwargs: Any) -> Any:
+    if _Document is None:  # pragma: no cover
+        raise RuntimeError(LANGCHAIN_IMPORT_ERROR or "langchain-core not installed")
+    return _Document(**kwargs)
+
+
+try:
+    from langchain_core.documents import Document as _Document  # type: ignore
+    from langchain_core.vectorstores import (
+        VectorStore as _VectorStoreBase,  # type: ignore
+    )
+
+    LANGCHAIN_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    LANGCHAIN_IMPORT_ERROR = (
+        "langchain-core is not installed. Install with: pip install langchain-core"
+    )
+    logger.debug(LANGCHAIN_IMPORT_ERROR)
+
+
+def _document_from_hit(hit: Dict[str, Any], include_score: bool = True) -> Any:
+    metadata, _ = _hit_layers(hit)
+    node_id = _hit_id(hit)
+    doc_meta = {
+        **metadata,
+        "node_id": node_id,
+        "node_type": _hit_type(hit),
+    }
+    if include_score:
+        doc_meta["score"] = _hit_score(hit, default=0.0)
+    return _make_document(
+        page_content=_hit_content(hit),
+        metadata=doc_meta,
+    )
+
+
+class SemanticaVectorStore(_VectorStoreBase):  # type: ignore[misc]
+    """Wrap Semantica hybrid search as a LangChain ``VectorStore``.
+
+    Args:
+        hybrid: A semantica.vector_store.HybridSearch instance.
+        vector_store: Optional Semantica vector store passed through to
+            ``HybridSearch.add_texts``.
+    """
+
+    hybrid: Any
+    vector_store: Any = None
+
+    def __init__(self, hybrid: Any, vector_store: Any = None, **kwargs: Any) -> None:
+        if LANGCHAIN_AVAILABLE:
+            super().__init__(**kwargs)
+        else:
+            super().__init__()
+        self.hybrid = hybrid
+        self.vector_store = vector_store
+
+    # -- required VectorStore API ------------------------------------------
+    def add_texts(
+        self,
+        texts: Iterable[str],
+        metadatas: Optional[List[Dict[str, Any]]] = None,
+        **kwargs: Any,
+    ) -> List[str]:
+        """Embed and store texts; return the generated IDs.
+
+        Delegates to the Semantica ``VectorStore.add_documents`` backing the
+        HybridSearch instance (or to ``hybrid.vector_store`` if provided).
+        """
+        if self.vector_store is not None:
+            return self.vector_store.add_documents(
+                list(texts), metadata=metadatas, **kwargs
+            )
+        vs = getattr(self.hybrid, "vector_store", None)
+        if vs is not None and hasattr(vs, "add_documents"):
+            return vs.add_documents(list(texts), metadata=metadatas, **kwargs)
+        raise ValueError(
+            "SemanticaVectorStore requires a Semantica vector store with "
+            "add_documents (pass vector_store=... to the HybridSearch or to "
+            "SemanticaVectorStore)"
+        )
+
+    def similarity_search(self, query: str, k: int = 4, **kwargs: Any) -> List[Any]:
+        """Return documents most similar to the query."""
+        return [_document_from_hit(hit) for hit in self.hybrid.search(query, k=k)]
+
+    def similarity_search_with_score(
+        self, query: str, k: int = 4, **kwargs: Any
+    ) -> List[Any]:
+        """Return (document, score) pairs."""
+        return [
+            (
+                _document_from_hit(hit, include_score=False),
+                _hit_score(hit, default=0.0),
+            )
+            for hit in self.hybrid.search(query, k=k)
+        ]
+
+    @classmethod
+    def from_texts(
+        cls,
+        texts: List[str],
+        embedding: Any = None,
+        metadatas: Optional[List[Dict[str, Any]]] = None,
+        **kwargs: Any,
+    ) -> "SemanticaVectorStore":
+        """Build a store from a list of texts (LangChain convention).
+
+        Requires a pre-configured ``hybrid`` instance passed via kwargs.
+        """
+        hybrid = kwargs.pop("hybrid", None)
+        if hybrid is None:
+            raise ValueError(
+                "SemanticaVectorStore.from_texts requires a 'hybrid' "
+                "HybridSearch instance as a keyword argument"
+            )
+        store = cls(hybrid=hybrid, **kwargs)
+        store.add_texts(texts, metadatas=metadatas)
+        return store

integrations/openclaw/mcp_tool.py

@@ -116,7 +116,41 @@ class OpenClawKGTool:
     )
 
     def __init__(self, base_url: str = "http://localhost:8000", timeout: int = 30) -> None:
-        self.base_url = base_url.rstrip("/")
+        # Validate base_url at construction time so callers get an immediate,
+        # actionable error rather than a cryptic failure on the first request.
+        # allow_private_ips=True because the documented default (localhost:8000)
+        # is intentionally a local Semantica server; the scheme check and
+        # URL-structure check still apply unconditionally.
+        try:
+            from semantica.ingest.ssrf import validate_url_for_request
+            validate_url_for_request(base_url, allow_private_ips=True)
+        except ImportError:
+            # semantica.ingest not installed in minimal openclaw-only environments;
+            # mirror the structural checks that validate_url_for_request performs
+            # unconditionally (before allow_private_ips is consulted), so the
+            # guarantee in the comment above — "scheme check and URL-structure check
+            # still apply unconditionally" — holds in this path too.
+            from urllib.parse import urlparse as _urlparse
+            if not isinstance(base_url, str) or not base_url.strip():
+                raise ValueError("OpenClawKGTool base_url must be a non-empty string.")
+            _parsed = _urlparse(base_url.strip())
+            _scheme = (_parsed.scheme or "").lower()
+            if _scheme not in ("http", "https"):
+                raise ValueError(
+                    f"OpenClawKGTool base_url scheme '{_parsed.scheme}' is not permitted. "
+                    "Only http and https are allowed."
+                )
+            if not _parsed.netloc:
+                raise ValueError(
+                    f"Invalid OpenClawKGTool base_url '{base_url}': "
+                    "URL must include a netloc (domain or host)."
+                )
+            if not _parsed.hostname:
+                raise ValueError(
+                    f"Invalid OpenClawKGTool base_url '{base_url}': "
+                    "URL must include a hostname."
+                )
+        self.base_url = base_url.strip().rstrip("/")
         self.timeout = timeout
         self._session: Any = None
 

mcp/__init__.py

@@ -21,6 +21,17 @@ Configure in Claude Desktop, Windsurf, Cline, Continue, VS Code:
     }
 """
 
+import os
+
+# MCP stdio framing IS stdout: any progress bar or console renderer that writes
+# to stdout would interleave with the JSON-RPC stream and corrupt framing for
+# every client.  This package is always used as an MCP stdio server, so force
+# progress tracking off for the entire process.  Set before importing server /
+# tools so the Semantica progress-tracker singleton is never created with
+# output enabled (the singleton reads this variable at construction time and
+# the enabled.setter re-checks it, so later re-enable attempts are also blocked).
+os.environ["SEMANTICA_DISABLE_PROGRESS"] = "1"
+
 # `semantica.__version__` is the authoritative package version — see
 # semantica/mcp_server/__init__.py for why it is used directly rather than
 # importlib.metadata.version("semantica").

mcp/tools/export.py

@@ -80,7 +80,12 @@ def handle_export_graph(args: dict) -> dict:
         if rdf_fmt:
             try:
                 from semantica.export import RDFExporter
-                rdf_str = RDFExporter().export_to_rdf(graph, format=rdf_fmt)
+                # RDFExporter.export_to_rdf() expects the canonical kg dict
+                # {"entities": [...], "relationships": [...]}, not a ContextGraph
+                # object.  Convert before handing off; passing the raw graph
+                # caused AttributeError: 'ContextGraph' object has no attribute
+                # 'get' on every RDF format.
+                rdf_str = RDFExporter().export_to_rdf(graph.to_kg_dict(), format=rdf_fmt)
                 return {"format": rdf_fmt, "data": rdf_str}
             except Exception as exc:
                 return {"error": f"RDF export failed: {exc}"}

poc_runner.py

@@ -187,15 +187,6 @@ def poc_vuln3():
             })
         return nodes
 
-    # Simulate the CSV parser — mirrors export_import.py lines 131-133
-    def parse_import_csv_row(row: dict) -> dict:
-        """Mirrors export_import.py CSV node ID extraction (no sanitization)."""
-        node_id = row.get("id") or row.get("node_id") or row.get(":ID") or row.get("_id")
-        return {
-            "id": str(node_id),  # ← UNSANITIZED
-            "type": row.get("type", "entity"),
-        }
-
     # Attack payloads
     payloads = [
         # Header injection payload (chained with VULN-1)

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "semantica"
-version = "0.6.6"
+version = "0.6.7"
 description = "Graph-Native Infrastructure for Context and Accountable AI Systems: context graphs, decision intelligence, full provenance tracking, and explainable reasoning engines — every AI decision traceable, every output auditable."
 readme = "README.md"
 license = { text = "MIT" }
@@ -49,7 +49,14 @@ dependencies = [
   "scipy>=1.13.1",
   "scikit-learn>=1.7.2",
   "umap-learn>=0.5.12",
-  "spacy>=3.4.0",
+  # thinc (spacy's core dep) dropped Python 3.9 wheels at 8.3.10, and later
+  # spacy patch releases (3.8.8+) require thinc>=8.3.9-only-on-3.10+ ranges,
+  # which forces a source build that fails outright on 3.9 (see Install
+  # Matrix run history). Capping both keeps 3.9 on the last wheel-compatible
+  # pair; 3.10+ is left unconstrained to always get the latest spacy/thinc.
+  "spacy>=3.4.0,<3.8.8; python_version < '3.10'",
+  "spacy>=3.4.0; python_version >= '3.10'",
+  "thinc<8.3.5; python_version < '3.10'",
   "transformers>=4.20.0",
   "torch>=1.13.1",
   "sentence-transformers>=2.2.0",
@@ -107,11 +114,12 @@ llm-gemini = ["google-genai>=0.1.0"]
 llm-anthropic = ["anthropic>=0.122.0"]
 llm-ollama = ["ollama>=0.1.0"]
 llm-deepseek = ["openai>=1.0.0"]
+llm-novita = ["openai>=1.0.0"]
 llm-litellm = ["litellm>=1.83.9"]
 llm-instructor = ["instructor>=1.15.3"]
 
 llm-all = [
-  "semantica[llm-openai,llm-groq,llm-gemini,llm-anthropic,llm-ollama,llm-deepseek,llm-litellm,llm-instructor]"
+  "semantica[llm-openai,llm-groq,llm-gemini,llm-anthropic,llm-ollama,llm-deepseek,llm-novita,llm-litellm,llm-instructor]"
 ]
 
 # ---- Document Parsing ----
@@ -124,11 +132,13 @@ shacl = ["pyshacl>=0.25.0"]
 db-snowflake = ["snowflake-connector-python>=4.6.0", "cryptography>=49.0.0"]
 db-databricks = ["databricks-sdk>=0.60.0", "databricks-sql-connector>=4.0.0"]
 db-arrow = ["pyarrow>=24.0.0"]
+db-salesforce = ["simple-salesforce>=1.12.0"]
 ingest-parquet = ["pyarrow>=24.0.0"]
 ingest-arrow = ["pyarrow>=24.0.0"]
+ingest-sap = ["requests>=2.28.0"]
 
 db-all = [
-  "semantica[db-snowflake,db-databricks,db-arrow]"
+  "semantica[db-snowflake,db-databricks,db-salesforce,db-arrow]"
 ]
 
 # ---- Embedding / Models ----
@@ -206,6 +216,7 @@ agno = ["agno>=1.0.0"]
 # needed (it pulls vulnerable transitive deps like chromadb) and would only
 # duplicate the prebuilt tooling users can install separately.
 crewai = ["crewai>=0.80.0"]
+langchain = ["langchain-core>=0.3.0"]
 
 # ---- File Watching ----
 watch = ["watchdog>=6.0.0"]
@@ -253,7 +264,7 @@ explorer-lite = [
 # dependency-audit/security gates.  Install it explicitly via ``semantica[crewai]``.
 all = [
   "semantica[dev,viz,infra,cloud,monitoring,watch,llm-all,models-huggingface,split-all,graph-all,tripletstore-oxigraph,vectorstore-all,parse-docling,ingest-parquet,ingest-arrow,shacl,explorer]",
-  "semantica[dev,viz,infra,cloud,monitoring,watch,llm-all,models-huggingface,split-all,graph-all,tripletstore-oxigraph,vectorstore-all,parse-docling,ingest-parquet,ingest-arrow,shacl,agno]"
+  "semantica[dev,viz,infra,cloud,monitoring,watch,llm-all,models-huggingface,split-all,graph-all,tripletstore-oxigraph,vectorstore-all,parse-docling,ingest-parquet,ingest-arrow,shacl,agno,langchain]"
 ]
 
 # ---------------- ENTRYPOINTS ----------------

semantica/__init__.py

@@ -10,7 +10,7 @@ Main exports:
     - Config: Configuration management
 """
 
-__version__ = "0.6.6"
+__version__ = "0.6.7"
 __author__ = "Semantica Contributors"
 __license__ = "MIT"
 

semantica/change_management/version_storage.py

@@ -31,6 +31,7 @@ import hashlib
 import json
 import sqlite3
 import threading
+import warnings
 from abc import ABC, abstractmethod
 from datetime import datetime
 from pathlib import Path
@@ -62,6 +63,12 @@ def create_graph_snapshot_record(
     """
     Creates a standardized snapshot metadata record for a named graph.
 
+    .. deprecated::
+        ``create_graph_snapshot_record()`` is deprecated and will be removed in
+        a future major version. It has no callers inside Semantica; build the
+        record inline and checksum it with
+        :func:`semantica.change_management.compute_checksum` instead.
+
     Args:
         version_id: Unique identifier for this snapshot
         graph_uri: The underlying named graph URI in the triplet store
@@ -69,6 +76,13 @@ def create_graph_snapshot_record(
         description: Purpose or context of the snapshot
         metadata: Additional tags or pipeline context
     """
+    warnings.warn(
+        "create_graph_snapshot_record() is deprecated and will be removed in a "
+        "future major version. Build the snapshot record inline and use "
+        "semantica.change_management.compute_checksum() instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     
     record = {
         "label": version_id,

semantica/cli.py

@@ -1732,6 +1732,93 @@ def embed(ctx: click.Context) -> None:
         click.echo(ctx.get_help())
 
 
+def _json_default(obj) -> object:
+    """JSON serialiser that converts NumPy scalars/arrays to native Python types.
+
+    Falls back to ``str()`` for everything else so the writer never crashes on
+    unexpected types (e.g. ``datetime``, custom domain objects).
+    """
+    try:
+        import numpy as np  # local import — only needed when result contains numpy
+        if isinstance(obj, np.ndarray):
+            return obj.tolist()
+        if isinstance(obj, np.generic):
+            return obj.item()
+    except ImportError:
+        pass
+    return str(obj)
+
+
+def _write_result_output(out_path: Path, result) -> None:
+    """Serialize a structured CLI result (dict or list) for ``--output``.
+
+    Domain commands like ``deduplicate`` and ``ontology align`` produce dicts
+    and lists, not numeric matrices — routing them through the embeddings
+    writer rejected their shapes and extensions (.csv is documented for
+    deduplicate). JSON-family formats serialize anything; CSV serializes a
+    list of dicts (or a single dict as one row).
+
+    Accepted extensions: .json, .jsonl, .csv  (no-extension and .txt are
+    rejected so the path reported to the caller always matches the file
+    actually created, consistent with every other --output in the CLI).
+    """
+    import json as _json
+
+    suffix = out_path.suffix.lower()
+
+    # ── JSON ────────────────────────────────────────────────────────────────
+    if suffix == ".json":
+        with open(out_path, "w", encoding="utf-8") as fh:
+            _json.dump(result, fh, indent=2, default=_json_default)
+        return
+
+    # ── JSON Lines ──────────────────────────────────────────────────────────
+    # Every record must occupy exactly one line.  Wrap a bare dict in a list
+    # so callers never need to know whether their result is singular or plural.
+    if suffix == ".jsonl":
+        items = result if isinstance(result, list) else [result]
+        with open(out_path, "w", encoding="utf-8") as fh:
+            for item in items:
+                fh.write(_json.dumps(item, default=_json_default) + "\n")
+        return
+
+    # ── CSV ─────────────────────────────────────────────────────────────────
+    if suffix == ".csv":
+        import pandas as pd
+
+        rows = result if isinstance(result, list) else [result]
+        if not rows:
+            raise click.ClickException(
+                "No results to write — output file not created."
+            )
+        # Normalise numpy scalars/arrays to Python natives so to_csv() does
+        # not fall back to repr() strings for array-valued cells.
+        def _normalise(row):
+            if not isinstance(row, dict):
+                return row
+            out = {}
+            for k, v in row.items():
+                try:
+                    import numpy as np
+                    if isinstance(v, np.ndarray):
+                        v = v.tolist()
+                    elif isinstance(v, np.generic):
+                        v = v.item()
+                except ImportError:
+                    pass
+                out[k] = v
+            return out
+
+        pd.DataFrame([_normalise(r) for r in rows]).to_csv(out_path, index=False)
+        return
+
+    # ── unsupported ─────────────────────────────────────────────────────────
+    display = suffix if suffix else "(no extension)"
+    raise click.ClickException(
+        f"Unsupported output format '{display}'. Use .json, .jsonl, or .csv"
+    )
+
+
 @embed.command("generate")
 @click.argument("input_path")
 @click.option("--model",
@@ -2032,7 +2119,7 @@ def deduplicate(
         except ImportError as exc:
             raise click.ClickException(f"Deduplication module not available: {exc}") from exc
         if output:
-            Path(output).write_text(json.dumps(result, default=str), encoding="utf-8")
+            _write_result_output(Path(output), result)
             _ok(cli_ctx, f"Wrote {output}")
         elif _is_json(cli_ctx, local_json):
             _jecho(result if isinstance(result, (dict, list)) else {"result": str(result)})
@@ -3156,7 +3243,7 @@ def ontology_align(cli_ctx: CLIContext, source: str, target: str, strategy: str,
         except ImportError as exc:
             raise click.ClickException(f"Ontology module not available: {exc}") from exc
         if output:
-            Path(output).write_text(json.dumps(result, default=str), encoding="utf-8")
+            _write_result_output(Path(output), result)
             _ok(cli_ctx, f"Wrote {output}")
         elif _is_json(cli_ctx, local_json):
             _jecho(result if isinstance(result, dict) else {"alignments": str(result)})
@@ -3627,19 +3714,61 @@ def store_stats(cli_ctx: CLIContext, backend: str, fmt: str, local_json: bool) -
     _run_with_error_handling(_action)
 
 
+_MIGRATE_SUPPORTED_BACKENDS = {"faiss", "sqlite", "pgvector"}
+_MIGRATE_BATCH_SIZE = 500
+
+
+def _migrate_backend_config(vs_cfg: Dict[str, Any], backend: str) -> Dict[str, Any]:
+    """Resolve per-backend config out of the vector_store config section.
+
+    Supports both a per-backend nested shape (``vector_store.faiss.dimension``)
+    and the common flat single-backend shape (``vector_store.backend`` +
+    sibling keys), since either can appear depending on how many backends a
+    user has configured.
+    """
+    nested = vs_cfg.get(backend)
+    if isinstance(nested, dict):
+        return dict(nested)
+    if vs_cfg.get("backend") == backend:
+        return {k: v for k, v in vs_cfg.items() if k != "backend"}
+    return {}
+
+
+def _require_faiss_index_path(cfg: Dict[str, Any], role: str) -> str:
+    """FAISS has no server to hold state between commands: a fresh FAISSStore
+    starts empty and nothing outside the process persists it, so migration
+    needs an explicit on-disk index to read from or write to."""
+    index_path = cfg.get("index_path")
+    if not index_path:
+        raise click.ClickException(
+            f"faiss as migration {role} requires 'index_path' in the vector_store "
+            f"config (vector_store.faiss.index_path or vector_store.index_path "
+            f"when faiss is the configured backend)."
+        )
+    return index_path
+
+
 @store.command("migrate")
 @click.option("--from", "from_backend", required=True)
 @click.option("--to", "to_backend", required=True)
 @click.option("--namespace", default=None)
 @click.option("--dry-run", "local_dry", is_flag=True, default=False)
+@click.option("--json", "local_json", is_flag=True, default=False)
 @click.pass_obj
 def store_migrate(cli_ctx: CLIContext, from_backend: str, to_backend: str,
-                  namespace: Optional[str], local_dry: bool) -> None:
+                  namespace: Optional[str], local_dry: bool, local_json: bool) -> None:
     """Migrate data between backends.
 
+    Direct migration is only wired up between faiss, sqlite, and pgvector -
+    these are the backends whose storage contract supports paging through
+    every stored vector. Migrating to or from qdrant, pinecone, milvus, or
+    weaviate still needs the export/reindex workaround below, since each of
+    those needs its own enumeration design (Qdrant scroll, Pinecone list,
+    etc.) that hasn't been built yet.
+
     \b
     Example:
-      semantica store migrate --from faiss --to qdrant --namespace production --dry-run
+      semantica store migrate --from faiss --to sqlite --namespace production --dry-run
     """
     cli_ctx = _require_ctx(cli_ctx)
 
@@ -3647,13 +3776,76 @@ def store_migrate(cli_ctx: CLIContext, from_backend: str, to_backend: str,
         if _is_dry(cli_ctx, local_dry):
             _dry(cli_ctx, "migrate", from_backend=from_backend, to_backend=to_backend)
             return
-        raise click.ClickException(
-            f"Direct backend migration ({from_backend} → {to_backend}) is not yet supported "
-            "by the vector store layer. To migrate, export your data first:\n"
-            "  semantica export --format parquet --output dump.parquet\n"
-            f"  semantica embed index dump.parquet --store {to_backend}"
-            + (f" --namespace {namespace}" if namespace else "")
-        )
+
+        if from_backend not in _MIGRATE_SUPPORTED_BACKENDS or to_backend not in _MIGRATE_SUPPORTED_BACKENDS:
+            raise click.ClickException(
+                f"Direct backend migration ({from_backend} → {to_backend}) is only supported "
+                f"between {', '.join(sorted(_MIGRATE_SUPPORTED_BACKENDS))}. To migrate involving "
+                "another backend, export your data first:\n"
+                "  semantica export --format parquet --output dump.parquet\n"
+                f"  semantica embed index dump.parquet --store {to_backend}"
+                + (f" --namespace {namespace}" if namespace else "")
+            )
+
+        from .vector_store import VectorStore
+
+        vs_cfg = cli_ctx.config.to_dict().get("vector_store", {}) or {}
+        source_cfg = _migrate_backend_config(vs_cfg, from_backend)
+        dest_cfg = _migrate_backend_config(vs_cfg, to_backend)
+
+        source_index_path = None
+        if from_backend == "faiss":
+            source_index_path = _require_faiss_index_path(source_cfg, "source")
+        dest_index_path = None
+        if to_backend == "faiss":
+            dest_index_path = _require_faiss_index_path(dest_cfg, "destination")
+
+        source = VectorStore(backend=from_backend, config=source_cfg)
+        if source_index_path:
+            source._backend_store.load_index(source_index_path)
+
+        source_dimension = getattr(source._backend_store, "dimension", None)
+        if source_dimension and "dimension" not in dest_cfg:
+            dest_cfg["dimension"] = source_dimension
+
+        dest = VectorStore(backend=to_backend, config=dest_cfg)
+        if dest_index_path and Path(dest_index_path).exists():
+            dest._backend_store.load_index(dest_index_path)
+
+        migrated = 0
+        vectors_batch: List[Any] = []
+        metadata_batch: List[Dict[str, Any]] = []
+        ids_batch: List[str] = []
+
+        def _flush() -> None:
+            nonlocal migrated
+            if not vectors_batch:
+                return
+            dest.store_vectors(list(vectors_batch), list(metadata_batch), ids=list(ids_batch))
+            migrated += len(vectors_batch)
+            vectors_batch.clear()
+            metadata_batch.clear()
+            ids_batch.clear()
+
+        for item in source.iter_vectors(batch_size=_MIGRATE_BATCH_SIZE):
+            meta = dict(item.get("metadata") or {})
+            if namespace and "namespace" not in meta:
+                meta["namespace"] = namespace
+            vectors_batch.append(item["vector"])
+            metadata_batch.append(meta)
+            ids_batch.append(item["id"])
+            if len(vectors_batch) >= _MIGRATE_BATCH_SIZE:
+                _flush()
+        _flush()
+
+        if dest_index_path and migrated:
+            dest._backend_store.save_index(dest_index_path)
+
+        result = {"from": from_backend, "to": to_backend, "migrated": migrated}
+        if _is_json(cli_ctx, local_json):
+            _jecho(result)
+        else:
+            _ok(cli_ctx, f"Migrated {migrated} vectors from {from_backend} to {to_backend}")
 
     _run_with_error_handling(_action)
 

semantica/conflicts/config.py

@@ -109,7 +109,7 @@ class ConflictsConfig:
             if value:
                 try:
                     if type_func == bool:
-                        self._configs[config_key] = value.lower() in (
+                        self._configs[config_key] = value.strip().lower() in (
                             "true",
                             "1",
                             "yes",
@@ -136,12 +136,12 @@ class ConflictsConfig:
         if value:
             try:
                 # Try to convert to appropriate type
-                if isinstance(default, int):
+                if isinstance(default, bool):
+                    return value.strip().lower() in ("true", "1", "yes", "on")
+                elif isinstance(default, int):
                     return int(value)
                 elif isinstance(default, float):
                     return float(value)
-                elif isinstance(default, bool):
-                    return value.lower() in ("true", "1", "yes", "on")
                 return value
             except (ValueError, TypeError):
                 pass

semantica/context/agent_memory.py

@@ -1286,13 +1286,19 @@ class AgentMemory:
         """
         return self.retrieve(content, max_results=limit, **kwargs)
 
-    def find_by_entity(self, entity_id: str, limit: int = 10) -> List[Dict[str, Any]]:
+    def find_by_entity(
+        self, entity_id: str, limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
         """
         Find by entity.
 
         Args:
             entity_id: Entity ID to search for
-            limit: Maximum results (default: 10)
+            limit: Maximum results. None (the default) returns ALL matches.
+                The previous default of 10 silently truncated results — an
+                erasure workflow computing "what references this entity"
+                from a truncated page would leave the remainder live
+                (#1018). Callers that want pagination pass an explicit limit.
 
         Returns:
             List of memory dicts containing the entity
@@ -1308,9 +1314,9 @@ class AgentMemory:
                     if mem_dict:
                         results.append(mem_dict)
                     break
-            if len(results) >= limit:
+            if limit is not None and len(results) >= limit:
                 break
-        return results[:limit]
+        return results if limit is None else results[:limit]
 
     def find_by_relationship(
         self, relationship_type: str, limit: int = 10

semantica/context/context_graph.py

@@ -899,6 +899,11 @@ class ContextGraph:
                 return
             node.properties.update(attributes)
             node.metadata.update(attributes)
+            # Keep derived decision indexes consistent when a decision node is
+            # mutated so that category / entity / temporal lookups reflect the
+            # new property values without requiring a full graph reload.
+            if (getattr(node, "node_type", None) or "").lower() == "decision":
+                self._sync_decision_from_node(node_id)
 
         if getattr(self, "mutation_callback", None) and not getattr(
             self, "_suspend_mutation_callback", False
@@ -1291,6 +1296,14 @@ class ContextGraph:
                 if link_id:
                     self._unresolved_links[link_id] = link_meta
 
+            # Rebuild all derived decision indexes from the freshly-loaded
+            # nodes so that find_precedents_by_scenario, find_similar_decisions,
+            # and all decision analytics work correctly after a reload.
+            # _rebuild_decision_indexes() unconditionally clears the old indexes
+            # first, so repeated load_from_file calls never accumulate stale
+            # entries from a previous file.
+            self._rebuild_decision_indexes()
+
         self.logger.info(f"Loaded context graph from {path}")
 
     @staticmethod
@@ -1633,6 +1646,8 @@ class ContextGraph:
             self._analytics_cache.clear()
             self._retractions.clear()
             self._tombstones.clear()
+            # Rebuild derived decision indexes from the freshly-loaded nodes.
+            self._rebuild_decision_indexes()
 
         if self.mutation_callback and not self._suspend_mutation_callback:
             mutation_events = [
@@ -2825,6 +2840,12 @@ class ContextGraph:
             self._unresolved_links.clear()
             self._retractions.clear()
             self._tombstones.clear()
+            # Reset derived decision indexes so that decision queries against
+            # a cleared graph return empty results rather than stale data.
+            self._decisions = {}
+            self._decision_index = defaultdict(set)
+            self._entity_index = defaultdict(set)
+            self._temporal_index = []
         self.logger.debug("Graph state fully cleared.")
 
     # --- Internal Helpers ---
@@ -3482,6 +3503,9 @@ class ContextGraph:
             )
             self._add_internal_edge(edge)
 
+        # Rebuild derived decision indexes from the now-populated node store.
+        self._rebuild_decision_indexes()
+
     def state_at(self, timestamp: Union[str, int, float, datetime]) -> Dict[str, Any]:
         """Return a serializable snapshot of graph state valid at the given time."""
         at_time = self._normalize_timestamp(timestamp)
@@ -4707,6 +4731,7 @@ class ContextGraph:
                 scenario=decision["scenario"],
                 decision_maker=decision.get("decision_maker", ""),
                 reasoning=decision["reasoning"],
+                recorded_at=decision.get("recorded_at", ""),
                 **safe_metadata,
                 **extra_properties,
             )
@@ -4788,20 +4813,288 @@ class ContextGraph:
             return False
         return True
     
-    def _calculate_decision_content_similarity(self, scenario: str, decision: Dict[str, Any]) -> float:
-        """Calculate content similarity between scenario and decision."""
+    # ── decision-index helpers ────────────────────────────────────────────────
+
+    # Protected set of node properties whose values are *core* decision fields
+    # so that we can distinguish them from user-supplied metadata when
+    # rebuilding the in-memory indexes from a persisted node.
+    _DECISION_CORE_FIELDS: frozenset = frozenset({
+        "id", "category", "scenario", "reasoning", "outcome", "confidence",
+        "entities", "decision_maker", "timestamp", "recorded_at",
+        "valid_from", "valid_until", "content",
+    })
+
+    def _rebuild_decision_indexes(self) -> None:
+        """Rebuild all derived decision indexes from the current node store.
+
+        This method is the single authoritative rebuild path.  It must be
+        called (under the graph lock) after any operation that wholesale
+        replaces ``self.nodes`` — namely ``load_from_file`` (JSON and Markdown
+        paths) and ``from_dict``.
+
+        Contract:
+        - Unconditionally clears ``_decisions``, ``_decision_index``,
+          ``_entity_index``, and ``_temporal_index`` before rebuilding so that
+          repeated calls never accumulate stale entries.
+        - Derives ``_decisions[node_id]["metadata"]`` from the full set of
+          node properties, excluding the protected core fields, so that
+          user-supplied metadata survives the round-trip.
+        - Runs under ``self._lock`` when called from load paths; callers that
+          already hold the lock must invoke ``_rebuild_decision_indexes``
+          inside the lock block.
+        """
+        # Always start fresh so repeated loads don't accumulate stale entries.
+        self._decisions: Dict[str, Any] = {}
+        self._decision_index: Dict[str, set] = defaultdict(set)
+        self._entity_index: Dict[str, set] = defaultdict(set)
+        self._temporal_index: List[Tuple[str, float]] = []
+
+        for node in self.nodes.values():
+            if (getattr(node, "node_type", None) or "").lower() != "decision":
+                continue
+
+            # Merge metadata and properties; properties win on collision.
+            meta: Dict[str, Any] = {}
+            meta.update(getattr(node, "metadata", {}) or {})
+            meta.update(getattr(node, "properties", {}) or {})
+
+            # Timestamp: keep whatever was stored (float epoch or ISO string).
+            # The temporal index uses it for sorting; downstream code handles
+            # both types via _normalize_timestamp.
+            raw_ts = meta.get("timestamp", 0.0)
+            try:
+                sort_ts = float(raw_ts)
+            except (TypeError, ValueError):
+                sort_ts = 0.0
+
+            # Entities may be stored as a list in meta or inferred from
+            # outgoing "involves" edges if the list field is absent/empty.
+            # _add_decision_to_graph creates entity nodes connected via
+            # "involves" edges; it does NOT store the list as a node property.
+            entities = meta.get("entities") or []
+            if not isinstance(entities, list):
+                entities = []
+            if not entities:
+                # Recover entity list from "involves" edges on this decision node
+                for edge in self._adjacency.get(node.node_id, []):
+                    if edge.edge_type == "involves":
+                        entities.append(edge.target_id)
+
+            # Everything that isn't a core field is user-supplied metadata.
+            extra_meta = {
+                k: v
+                for k, v in meta.items()
+                if k not in self._DECISION_CORE_FIELDS
+            }
+
+            decision: Dict[str, Any] = {
+                "id": node.node_id,
+                "category": meta.get("category", ""),
+                "scenario": meta.get("scenario", getattr(node, "content", "") or ""),
+                "reasoning": meta.get("reasoning", ""),
+                "outcome": meta.get("outcome", ""),
+                "confidence": float(meta.get("confidence", 0.0) or 0.0),
+                "entities": entities,
+                "decision_maker": meta.get("decision_maker"),
+                "timestamp": raw_ts,
+                "recorded_at": meta.get("recorded_at", ""),
+                "valid_from": getattr(node, "valid_from", None),
+                "valid_until": getattr(node, "valid_until", None),
+                # Preserve all non-core node properties as decision metadata so
+                # that user-supplied fields survive a save → load round-trip.
+                "metadata": extra_meta,
+            }
+
+            self._decisions[node.node_id] = decision
+
+            category = decision["category"]
+            if category:
+                self._decision_index[category].add(node.node_id)
+
+            for entity in entities:
+                self._entity_index[entity].add(node.node_id)
+
+            self._temporal_index.append((node.node_id, sort_ts))
+
+        self._temporal_index.sort(key=lambda x: x[1], reverse=True)
+
+    def _sync_decision_from_node(self, node_id: str) -> None:
+        """Synchronise a single decision index entry from the node store.
+
+        Called after ``add_node_attribute`` mutates a decision node so that
+        ``_decisions`` and the derived indexes stay consistent without
+        requiring a full rebuild of all decisions.
+        """
+        node = self.nodes.get(node_id)
+        if node is None:
+            return
+        if (getattr(node, "node_type", None) or "").lower() != "decision":
+            return
+
+        if not hasattr(self, "_decisions"):
+            # Indexes don't exist yet — a full rebuild is safer.
+            self._rebuild_decision_indexes()
+            return
+
+        # Remove stale index entries for this decision ID.
+        old = self._decisions.get(node_id)
+        if old:
+            old_cat = old.get("category", "")
+            if old_cat and node_id in self._decision_index.get(old_cat, set()):
+                self._decision_index[old_cat].discard(node_id)
+            for ent in old.get("entities", []):
+                self._entity_index[ent].discard(node_id)
+            self._temporal_index = [
+                (nid, ts) for nid, ts in self._temporal_index if nid != node_id
+            ]
+
+        # Rebuild the entry for this node and re-insert index entries.
+        meta: Dict[str, Any] = {}
+        meta.update(getattr(node, "metadata", {}) or {})
+        meta.update(getattr(node, "properties", {}) or {})
+
+        raw_ts = meta.get("timestamp", 0.0)
         try:
-            # Simple word-based similarity
+            sort_ts = float(raw_ts)
+        except (TypeError, ValueError):
+            sort_ts = 0.0
+
+        entities = meta.get("entities") or []
+        if not isinstance(entities, list):
+            entities = []
+        if not entities:
+            # Recover entity list from "involves" edges
+            for edge in self._adjacency.get(node_id, []):
+                if edge.edge_type == "involves":
+                    entities.append(edge.target_id)
+
+        extra_meta = {
+            k: v for k, v in meta.items() if k not in self._DECISION_CORE_FIELDS
+        }
+
+        decision: Dict[str, Any] = {
+            "id": node_id,
+            "category": meta.get("category", ""),
+            "scenario": meta.get("scenario", getattr(node, "content", "") or ""),
+            "reasoning": meta.get("reasoning", ""),
+            "outcome": meta.get("outcome", ""),
+            "confidence": float(meta.get("confidence", 0.0) or 0.0),
+            "entities": entities,
+            "decision_maker": meta.get("decision_maker"),
+            "timestamp": raw_ts,
+            "recorded_at": meta.get("recorded_at", ""),
+            "valid_from": getattr(node, "valid_from", None),
+            "valid_until": getattr(node, "valid_until", None),
+            "metadata": extra_meta,
+        }
+
+        self._decisions[node_id] = decision
+        if decision["category"]:
+            self._decision_index[decision["category"]].add(node_id)
+        for ent in entities:
+            self._entity_index[ent].add(node_id)
+        self._temporal_index.append((node_id, sort_ts))
+        self._temporal_index.sort(key=lambda x: x[1], reverse=True)
+
+    @staticmethod
+    def _char_bigrams(text: str) -> set:
+        """Character bigrams over whitespace-stripped text (CJK fallback).
+
+        Strips whitespace so CJK characters without word-separating spaces are
+        treated as a contiguous character sequence rather than a single token.
+        """
+        chars = "".join(text.lower().split())
+        return {chars[i:i + 2] for i in range(len(chars) - 1)}
+
+    @staticmethod
+    def _looks_cjk(text: str) -> bool:
+        """True if text contains CJK/Japanese/Korean script characters.
+
+        Used to gate the character-bigram similarity fallback so it only
+        activates for scripts where whitespace tokenisation doesn't work.
+        """
+        for ch in text:
+            code = ord(ch)
+            if (
+                0x4E00 <= code <= 0x9FFF     # CJK Unified Ideographs
+                or 0x3400 <= code <= 0x4DBF  # CJK Extension A
+                or 0x3040 <= code <= 0x30FF  # Hiragana + Katakana
+                or 0xAC00 <= code <= 0xD7A3  # Hangul Syllables
+                or 0x1100 <= code <= 0x11FF  # Hangul Jamo
+            ):
+                return True
+        return False
+
+    def _calculate_decision_content_similarity(self, scenario: str, decision: Dict[str, Any]) -> float:
+        """Calculate content similarity between scenario and decision.
+
+        Uses word-level Jaccard for space-separated languages.  For text where
+        whitespace tokenisation is unreliable (CJK/Japanese/Korean scripts, or
+        a query with no whitespace at all) a character-bigram Jaccard is
+        computed over the *stripped* character sequences instead.
+
+        The bigram fallback only activates when whitespace tokenisation would
+        not help — i.e. the query is CJK-like or has at most one whitespace
+        token — so it never contributes for ordinary multi-word English
+        queries, where incidental bigram overlap between unrelated sentences
+        would otherwise inflate scores.
+
+        The bigram side uses *Jaccard* (|A∩B|/|A∪B|), not the overlap
+        coefficient, so a 2-character query whose single bigram happens to
+        appear anywhere in a long document does not silently receive a score of
+        1.0.  A minimum bigram set size of 3 is required before the bigram
+        signal contributes; this prevents 1- and 2-character English queries
+        from polluting results while still allowing 3-character CJK phrases (2
+        bigrams) to match.
+        """
+        try:
+            decision_text = (
+                f"{decision['scenario']} {decision['reasoning']} "
+                f"{' '.join(decision['entities'])}"
+            )
+
+            # --- word-level Jaccard (primary metric for Latin/space-delimited) ---
             scenario_words = set(scenario.lower().split())
-            decision_text = f"{decision['scenario']} {decision['reasoning']} {' '.join(decision['entities'])}"
             decision_words = set(decision_text.lower().split())
-            
-            intersection = scenario_words.intersection(decision_words)
-            union = scenario_words.union(decision_words)
-            
-            return len(intersection) / len(union) if union else 0.0
-            
-        except Exception as e:
+            word_union = scenario_words | decision_words
+            word_sim = (
+                len(scenario_words & decision_words) / len(word_union)
+                if word_union
+                else 0.0
+            )
+
+            # --- character-bigram Jaccard (CJK / very-short-query fallback) ---
+            # Only used when whitespace tokenisation can't do the job: CJK-like
+            # scripts, or a query that is a single whitespace token (no spaces
+            # to split on).  Ordinary multi-word English queries rely on
+            # word_sim alone, so incidental bigram overlap between unrelated
+            # sentences can never inflate their score.
+            bigram_sim = 0.0
+            needs_bigram_fallback = (
+                self._looks_cjk(scenario) or len(scenario.split()) <= 1
+            )
+            if needs_bigram_fallback:
+                scenario_bigrams = self._char_bigrams(scenario)
+                decision_bigrams = self._char_bigrams(decision_text)
+
+                # Require at least 3 bigrams in the query before the bigram
+                # signal is used.  A 2-char query produces only 1 bigram; that
+                # single bigram is far too likely to appear as a substring of
+                # any English word and would produce a spuriously high overlap
+                # coefficient.  3 bigrams correspond to a 4-char stripped query
+                # (e.g. two CJK characters produce 1 bigram each → need ≥3
+                # chars stripped).
+                if len(scenario_bigrams) >= 3 and decision_bigrams:
+                    bigram_union = scenario_bigrams | decision_bigrams
+                    bigram_sim = (
+                        len(scenario_bigrams & decision_bigrams) / len(bigram_union)
+                        if bigram_union
+                        else 0.0
+                    )
+
+            return max(word_sim, bigram_sim)
+
+        except Exception:
             self.logger.exception("Content similarity calculation failed")
             return 0.0
     

semantica/context/decision_models.py

@@ -76,11 +76,11 @@ Production Use Cases:
     - Insurance: Claim decisions, underwriting assessments
 """
 
-from dataclasses import dataclass, field
-from datetime import datetime
-from typing import Any, Dict, List, Optional
 import json
 import uuid
+from dataclasses import InitVar, dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
 
 
 @dataclass
@@ -100,8 +100,9 @@ class Decision:
     valid_from: Optional[str] = None
     valid_until: Optional[str] = None
     metadata: Dict[str, Any] = field(default_factory=dict)
+    auto_generate_id: InitVar[bool] = True
     
-    def __post_init__(self, auto_generate_id: bool = True):
+    def __post_init__(self, auto_generate_id: bool) -> None:
         """Validate decision data."""
         if auto_generate_id and not self.decision_id:  # Handle both None and empty string
             self.decision_id = str(uuid.uuid4())
@@ -146,8 +147,9 @@ class DecisionContext:
     risk_factors: List[str]
     cross_system_inputs: Dict[str, Any] = field(default_factory=dict)
     metadata: Dict[str, Any] = field(default_factory=dict)
+    auto_generate_id: InitVar[bool] = True
     
-    def __post_init__(self, auto_generate_id: bool = True):
+    def __post_init__(self, auto_generate_id: bool) -> None:
         """Validate decision context data."""
         if auto_generate_id and not self.context_id:  # Handle both None and empty string
             self.context_id = str(uuid.uuid4())
@@ -184,8 +186,9 @@ class Policy:
     created_at: datetime
     updated_at: datetime
     metadata: Dict[str, Any] = field(default_factory=dict)
+    auto_generate_id: InitVar[bool] = True
     
-    def __post_init__(self, auto_generate_id: bool = True):
+    def __post_init__(self, auto_generate_id: bool) -> None:
         """Validate policy data."""
         if auto_generate_id and not self.policy_id:  # Handle both None and empty string
             self.policy_id = str(uuid.uuid4())
@@ -227,8 +230,9 @@ class PolicyException:
     approval_timestamp: datetime
     justification: str
     metadata: Dict[str, Any] = field(default_factory=dict)
+    auto_generate_id: InitVar[bool] = True
     
-    def __post_init__(self, auto_generate_id: bool = True):
+    def __post_init__(self, auto_generate_id: bool) -> None:
         """Validate policy exception data."""
         if auto_generate_id and not self.exception_id:  # Handle both None and empty string
             self.exception_id = str(uuid.uuid4())
@@ -265,8 +269,9 @@ class Precedent:
     similarity_score: float
     relationship_type: str  # "similar_scenario", "same_policy", "exception_precedent"
     metadata: Dict[str, Any] = field(default_factory=dict)
+    auto_generate_id: InitVar[bool] = True
     
-    def __post_init__(self, auto_generate_id: bool = True):
+    def __post_init__(self, auto_generate_id: bool) -> None:
         """Validate precedent data."""
         if auto_generate_id and not self.precedent_id:  # Handle both None and empty string
             self.precedent_id = str(uuid.uuid4())
@@ -305,8 +310,9 @@ class ApprovalChain:
     approval_context: str
     timestamp: datetime
     metadata: Dict[str, Any] = field(default_factory=dict)
+    auto_generate_id: InitVar[bool] = True
     
-    def __post_init__(self, auto_generate_id: bool = True):
+    def __post_init__(self, auto_generate_id: bool) -> None:
         """Validate approval chain data."""
         if auto_generate_id and not self.approval_id:  # Handle both None and empty string
             self.approval_id = str(uuid.uuid4())

semantica/context/graph_schema.py

@@ -6,6 +6,7 @@ including node labels, relationship types, and indexes for graph databases.
 """
 
 import json
+import warnings
 from typing import Dict, Any, List
 
 from ..graph_store import GraphStore
@@ -460,11 +461,25 @@ def drop_decision_schema(graph_store: GraphStore) -> None:
     """
     Drop decision tracking schema (for cleanup/testing).
     
+    .. deprecated::
+        ``drop_decision_schema()`` is deprecated and will be removed in a future
+        major version. It has no callers inside Semantica; issue the DROP
+        CONSTRAINT / DROP INDEX / DETACH DELETE statements directly against your
+        :class:`~semantica.graph_store.GraphStore` instead.
+
     Args:
         graph_store: Graph database instance
     """
     logger = get_logger(__name__)
     
+    warnings.warn(
+        "drop_decision_schema() is deprecated and will be removed in a future "
+        "major version. Issue the DROP CONSTRAINT / DROP INDEX / DETACH DELETE "
+        "statements directly against your GraphStore instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    
     try:
         # Drop constraints
         constraints = [