sm-divergence 0.7.0__tar.gz

sm_divergence-0.7.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: ci
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  ci-local:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Pin Python
+        run: uv python pin ${{ matrix.python-version }}
+      # The same gate as `make ci-local` — green locally == green here.
+      # sm-resolver (the kernel) resolves from PyPI.
+      - run: uv sync --extra dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy sm_divergence
+      - run: uv run pytest -v
+      - name: Examples run
+        run: |
+          uv run python examples/registry_divergence.py
+          uv run python examples/identity_key_divergence.py
+          uv run python examples/signed_self_description.py

sm_divergence-0.7.0/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+# Publish sm-divergence to PyPI on a version tag, via PyPI Trusted Publishing (OIDC).
+#
+# No API token anywhere: PyPI is told (once, in its web UI) to trust THIS repo +
+# THIS workflow file, and the `id-token: write` permission below lets the job
+# mint a short-lived OIDC token PyPI accepts. See PUBLISHING.md for the one-time
+# setup — including the prerequisite of publishing sm-resolver first and swapping
+# the git-URL dependency for a version spec (PyPI rejects direct references).
+#
+# Fires only when a tag like `v0.7.0` is pushed — never on normal commits.
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build + publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      # A job-level permissions block REPLACES the workflow-level one (it does not
+      # merge), so contents:read must be restated here or actions/checkout 404s on
+      # its own repo. Both lines are required.
+      contents: read # for actions/checkout
+      id-token: write # REQUIRED for Trusted Publishing — this is what replaces the token.
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Check the built distributions
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+
+      - name: Publish to PyPI
+        # No `with: password:` — the action uses the OIDC token automatically.
+        uses: pypa/gh-action-pypi-publish@release/v1

sm_divergence-0.7.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+uv.lock.tmp
+
+# Development & reconnaissance notes — design scoping, competitive research,
+# decision records. Kept local, never published.
+dev/

sm_divergence-0.7.0/CHANGELOG.md

@@ -0,0 +1,172 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/) and this project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.7.0] — 2026-07-04
+
+Self-description hardening — replay resistance, dogfooded distribution, and alias
+closure. Also the system's first **agent-equivocation** detection.
+
+### Added
+- **`seq` + supersession** — the self-description carries a monotonic `seq`
+  (signed); highest supersedes. `build_self_description(..., seq=N)` is now
+  required. Closes the replay hole where an unexpired but superseded description
+  could be served as "the agent's own signature."
+- **`reconcile_descriptions` / `DescriptionReconciliation`** — reconcile
+  descriptions gathered from multiple sources (`seq`-aware): the surviving
+  highest-`seq` `canonical`, plus findings `agent_equivocation` (two valid
+  descriptions at the same `seq` with different content → the agent's key signed
+  a conflict; correspondence fails closed), `omission`, and `stale_description`.
+- **`HttpDescriptionResolver` + `corroborate_descriptions`** — fetch + verify the
+  description from every source and reconcile, so the description's own
+  distribution (omission / replay) is corroborated, not trusted from one source.
+- **`AliasClosureResolver` + `binds_by_did` (discovery) / `binds_by_key`
+  (identity)** — a record reached via a self-asserted alias that does not bind
+  back to the agent's `did:key` contributes no claim, never a divergence. Prevents
+  a malicious agent from manufacturing a divergence by naming a victim's alias.
+
+### Changed
+- `build_self_description` gains a required `seq`; `SelfDescription` gains `seq`
+  and `content_key()`. `verify_self_description` parses and requires `seq`.
+
+## [0.6.0] — 2026-07-04
+
+The kernel is extracted. The source-agnostic core (`Resolver[T]`, `View`,
+`diff_views`, `Corroborator`, `Finding`) now lives in its own package,
+[`sm-resolver`](https://github.com/Sharathvc23/sm-resolver), and `sm-divergence`
+depends on it — the extraction the layered design was built toward, triggered
+once the identity layer joined discovery as a second consumer.
+
+### Changed
+- **`sm_divergence.core` removed**; the kernel is the `sm-resolver` dependency.
+  The top-level public API is unchanged (`from sm_divergence import Corroborator,
+  Finding, Resolver, Status, View, ViewT, diff_views, OMISSION, …` still work — now
+  re-exported from `sm-resolver`). Deep imports of `sm_divergence.core.*` no longer
+  exist; import from `sm_resolver` or the top level.
+- CI installs the private `sm-resolver` git dependency (needs the
+  `SM_RESOLVER_PAT` secret, or a public `sm-resolver`).
+- Version realigned (pyproject had drifted at 0.3.0 while the package was at 0.5.0).
+
+## [0.5.0] — 2026-07-04
+
+Signed portable-identity self-description (Phase 3) — identity correspondence
+becomes an agent-signed fact instead of caller-configured trust.
+
+### Added
+- **`sm_divergence.identity` self-description** — the agent signs a bundle
+  asserting its own aliases (its name per namespace) and service endpoints with
+  its `did:key`; a consumer verifies it offline and drives resolvers from the
+  *verified* names, so a source contradicting a signed alias/endpoint diverges
+  from the agent's own signature:
+  - `build_self_description(aliases, services, private_key)` → signed
+    `{descriptor, sig}` (did derived from the key; 24h default TTL).
+  - `verify_self_description(bundle)` → `SelfDescription | None` (offline sig +
+    freshness; string→string alias/service maps; never raises).
+  - `verified_descriptions(bundles)` → verify a map, keep only what verifies.
+  - `signed_alias_for(descriptions, namespace)` → a `did_for` / `locator_for`
+    backed by verified aliases; **falls back to the id when unverified**, so a
+    forged description can't redirect a resolver.
+- **`sm_divergence._signing`** — the shared Ed25519 / `did:key` / JCS primitives,
+  now used by both the discovery attestation adapter and the self-description
+  (behind the `attestation` extra). No behaviour change to `verified_did`.
+
+## [0.4.0] — 2026-07-04
+
+The identity layer (Phase 2 of the resolver-stack design) — the core's second
+consumer, proving the kernel generalizes past discovery. Corroborates the one
+field that must agree across an agent's DID methods: its verification key.
+
+### Added
+- **`sm_divergence.identity`** — key-consistency across DID methods, built on
+  the same core (`DidView` implements `View`; the resolvers produce it,
+  `Corroborator` + `diff_views` do the rest):
+  - `DidKeyResolver` — resolves a `did:key` offline (the self-certifying root);
+  - `DidWebResolver` — fetches a `did:web` document and reads its
+    `publicKeyMultibase`;
+  - `UniversalResolverResolver` — resolves any method via a DIF Universal
+    Resolver endpoint (`GET {base}/1.0/identifiers/{did}`).
+  A method that serves a different key than the root `did:key` is a `key`
+  divergence — the identity-layer analogue of endpoint tampering (a hijacked
+  domain, a stale mirror, or a lying resolver). Keys compare as `did:key`
+  multibase strings, so no crypto dependency is added.
+- Public: `DidView`, `DidKeyResolver`, `DidWebResolver`, `UniversalResolverResolver`,
+  `key_from_did_key`, `key_from_did_document`, `did_web_url`, `identity_did`, `KEY`.
+
+## [0.3.0] — 2026-07-04
+
+The core/discovery seam (Phase 1 of the resolver-stack design). Splits the
+package into a source-agnostic **kernel** and the discovery **layer** on top, so
+the kernel is extractable and a thin per-format adapter (e.g. a NANDA Index
+adapter) needs no discovery internals.
+
+### Added
+- **`sm_divergence.core`** — the layer-agnostic kernel: the `View` contract
+  (a claim reduced to named comparable fields via `comparable()`), a generic
+  `Resolver[T]` protocol, a generic `diff_views` (findings named after whatever
+  fields the view exposes), the `Corroborator[T]` orchestration, and `Finding`.
+  Nothing here knows any registry format. Intended to extract as a standalone
+  kernel once a second layer consumes it.
+- **`sm_divergence.discovery`** — the registry-integrity layer: `RecordView`
+  plus the `HttpByIdResolver` (NEST) and `NandaIndexV2Resolver` adapters, all
+  thin on the core.
+- `Corroborator`, `View`, `ViewT` are now public (for adapter/layer authors).
+
+### Changed
+- **Finding detail is uniform across layers.** A field divergence now carries
+  `{"field": <name>, "values": {source: value}}` (was `{"endpoints": {...}}` /
+  `{"dids": {...}}`), so any consumer parses findings the same way regardless of
+  layer or field. `omission` detail is unchanged. `kind` is unchanged
+  (`omission`, or the field name — `endpoint`/`did`).
+- Module layout moved under `core/` and `discovery/`. The top-level public API
+  (`from sm_divergence import …`) is unchanged; only deep imports
+  (`sm_divergence.client`, `.resolver`, `.index_v2`, `.models`, `.attestation`)
+  moved (to `sm_divergence.discovery.*`).
+
+## [0.2.0] — 2026-07-04
+
+Heterogeneous registries: corroborate across registries that speak *different*
+formats, not just different JSON at the same by-id endpoint.
+
+### Added
+- **The `Resolver` protocol** (`sm_divergence.resolver`, SPEC §6) — a per-registry
+  component mapping a canonical id to a normalized `(Status, RecordView)`. Each
+  resolver owns one registry's transport, record extraction, and native
+  verification; the diff is untouched because every resolver returns the same view.
+- **`HttpByIdResolver`** — the `GET /api/agents/{id}` shape (e.g. NEST), the v0.1
+  behavior repackaged as the first resolver.
+- **`NandaIndexV2Resolver`** (`sm_divergence.index_v2`) — the NANDA Index v2 two-hop
+  resolve (`/api/v1/resolve?locator=…` → `{registry_url, identifier}` → fetch the
+  record), normalized to a `RecordView`. `locator_for` maps a canonical id to the
+  Index's URN locator (identity correspondence is the caller's to define).
+- **`DivergenceDetector` accepts `str | Resolver`** — bare URLs are wrapped in
+  `HttpByIdResolver` (back-compatible), and resolver instances of different formats
+  can be mixed in one detector. Views are keyed by each resolver's `label`.
+- **CLI `--nanda-index URL`** — corroborate a NANDA Index v2 alongside `--registry`.
+
+### Changed
+- `looks_absent` (was `_looks_absent`) is now a shared public helper so every HTTP
+  resolver classifies soft-404 identically.
+
+## [0.1.0] — 2026-07-04
+
+Initial public release of sm-divergence — cross-registry divergence detection for
+accountable agent discovery.
+
+### Added
+- **The diff** (`diff_views`, SPEC §4) — the pure, deterministic core: per-registry
+  claims → `omission` / `endpoint` / `did` findings. No I/O; an unreachable
+  registry (an `error` claim) is excluded rather than counted as absence.
+- **Claim classification** (`fetch_view`, SPEC §3) — one registry's answer about one
+  id as `present` / `absent` / `error`, with hard-404 and soft-404 (`200` + not-found
+  body) both mapping to `absent`. Injectable by-id path and record adapter.
+- **`DivergenceDetector`** — fetch + diff + dedupe orchestration with an
+  `on_finding` callback that fires once per distinct finding; `check_once` one-shot.
+- **Verified-DID extraction** (`sm_divergence.attestation`, SPEC §5) — optional
+  `attestation` extra: Ed25519 / `did:key` / JCS verification of a self-certifying
+  record, plus a subject-match guard, feeding the `did` diff. Kept out of the core
+  so omission/endpoint checks carry no cryptographic dependency.
+- **CLI** — `python -m sm_divergence check --registry … --watch …`; exit `2` on any
+  divergence (cron/CI-friendly), `--json`, `--attestation`.
+- Whitepaper, spec, and governance documents.

sm_divergence-0.7.0/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing to sm-divergence
+
+Contributions are accepted under the Developer Certificate of Origin (DCO)
+sign-off model. Add `Signed-off-by: Your Name <you@example.com>` to every commit
+(`git commit -s`).
+
+## Change process
+
+1. Spec-affecting changes open a PR that updates the **spec (`SPEC.md`), the tests,
+   and the code together**. Drift between these is a defect — the `tests/` suite is
+   the authoritative behavioural specification of the diff.
+2. The gate is `make ci-local` (uv: `ruff` → `ruff format` → `mypy --strict` →
+   `pytest`). CI runs the same on Python 3.11 and 3.12. Push only when it is green.
+3. Every new guarantee needs a happy-path test; every classification and every
+   divergence kind needs its own case. The negative cases — unreachable ≠ absent,
+   one-verified-DID ≠ divergence, soft-404 = absent — are the point.
+
+## House rules
+
+- **A timeout is not a claim.** An unreachable or erroring source MUST be
+  excluded from the diff, never counted as an omission. This is the axiom the whole
+  library rests on; a change here needs an RFC-style PR to `SPEC.md` first.
+- **Only proven values disagree.** An unverified value (e.g. an unverified DID)
+  never enters the diff. Do not weaken the verification path.
+- **The diff stays pure and generic.** `diff_views` is deterministic, does no
+  I/O, never raises, and never learns its layer. All I/O lives in the resolvers;
+  a layer supplies a view (`comparable()`) and thin resolvers, nothing more.
+- **No new crypto.** The optional DID check reuses the family convention
+  (Ed25519 / `did:key` / JCS). Do not re-implement it elsewhere.
+- **No expansion of the classification (SPEC §3), the view contract (SPEC §4), or
+  the diff (SPEC §5) without an RFC-style PR to `SPEC.md` first.**

sm_divergence-0.7.0/GOVERNANCE.md

@@ -0,0 +1,31 @@
+# Governance
+
+## Scope
+
+| In scope | Out of scope |
+| --- | --- |
+| the claim classification (`present`/`absent`/`error`), the view contract (`comparable()`), the divergence diff (`omission` + per-field: `endpoint`/`did`/`key`/…), and the optional verified-DID extraction | the source itself; the record/document format and its signing (AgentFacts / self-certifying records / DID documents — the *tampering* half); a transparency log or witness network (single-source consistent lying); remediation policy on a finding; and each source's transport/schema (injected by a resolver) |
+
+The primitive owns one thing — answering *"do these sources disagree about this
+agent, and how?"* — across any layer (discovery, identity, and future
+capability/evidence). Anything outside the table belongs to a companion package
+or the caller.
+
+## Versioning
+
+Semantic Versioning 2.0.0. The claim classification (SPEC §3), the view contract
+(SPEC §4), and the diff (SPEC §5) are frozen within a major; a change requires an
+RFC-style PR to `SPEC.md` before code. The library API (`diff_views`,
+`Corroborator`, `DivergenceDetector`, `check_once`) follows the same major.
+
+## Conformance
+
+An implementation is conforming iff it reproduces the finding set in SPEC §10 for
+the specified claim inputs. The diff is pure and deterministic by construction, so
+conformance is mechanical.
+
+## Changes
+
+Spec-affecting changes: open a PR editing `SPEC.md` (and `WHITEPAPER.md` if the
+rationale moves), then the implementation and tests. Non-spec changes (adapters,
+CLI, performance) are ordinary PRs against a green `make ci-local`.

sm_divergence-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stellarminds.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sm_divergence-0.7.0/Makefile

@@ -0,0 +1,11 @@
+.PHONY: ci-local
+# One-command pre-push gate — the same steps CI runs, hard-failing on first red.
+ci-local:
+	uv sync --extra dev
+	uv run ruff check .
+	uv run ruff format --check .
+	uv run mypy sm_divergence
+	uv run pytest -v
+	uv run python examples/registry_divergence.py
+	uv run python examples/identity_key_divergence.py
+	uv run python examples/signed_self_description.py

sm_divergence-0.7.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: sm-divergence
+Version: 0.7.0
+Summary: Catch a cheating registry by corroboration — omission/endpoint/DID + cross-DID-method key divergence for federated agent discovery, on the sm-resolver kernel.
+Project-URL: Homepage, https://github.com/Sharathvc23/sm-divergence
+Project-URL: Spec, https://github.com/Sharathvc23/sm-divergence/blob/main/SPEC.md
+Project-URL: Whitepaper, https://github.com/Sharathvc23/sm-divergence/blob/main/WHITEPAPER.md
+Author: Sharath (Stellarminds)
+License: MIT
+License-File: LICENSE
+Keywords: accountability,ai-agents,discovery,federation,nanda,registry
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.24
+Requires-Dist: sm-resolver>=0.1
+Provides-Extra: attestation
+Requires-Dist: base58>=2.1; extra == 'attestation'
+Requires-Dist: cryptography>=42; extra == 'attestation'
+Requires-Dist: jcs>=0.2.1; extra == 'attestation'
+Provides-Extra: dev
+Requires-Dist: base58>=2.1; extra == 'dev'
+Requires-Dist: cryptography>=42; extra == 'dev'
+Requires-Dist: jcs>=0.2.1; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sm-divergence — catch a cheating registry by corroboration
+
+**Integrity for the sources agents resolve through. A registry (or a name
+service, or a DID method) can lie by omission, tampering, or equivocation;
+signing an artifact closes only tampering. This asks several sources the same
+questions and makes any disagreement loud.**
+
+Agents reach each other through middlemen — registries, indexes, DID methods —
+and a middleman can lie:
+
+- **tamper** — serve a false endpoint (or key) for an agent,
+- **omit** — hide an agent that is actually registered,
+- **equivocate** — tell different clients different things.
+
+A self-certifying artifact (a signed AgentFacts-style record, a `did:key`)
+defeats tampering — it can't be altered without breaking its signature. But *no
+signature can prove what a source chose **not** to serve.* Omission and
+equivocation are invisible to a single source.
+
+The cheap, robust defense is one decentralized discovery already hands you:
+**corroboration.** If an agent is reachable through two or more sources, ask all
+of them the same question and treat any disagreement as a signal. That is all
+this library does — enough to turn a silently cheating source into a loudly
+diverging one. See the [whitepaper](WHITEPAPER.md) for the argument and the
+[spec](SPEC.md) for the normative procedure.
+
+> **Not a transparency log.** Corroboration catches a source that disagrees with
+> its peers; it does not stop a *single* source lying *consistently* to a
+> first-time caller. That last mile is transparency-log territory (WHITEPAPER §7).
+
+## Where it fits
+
+A **DNS/CA-pillar** primitive in the [Project NANDA](https://projectnanda.org)
+four-pillar model (DNS / CA / Orchestration / Attestation): it protects the
+integrity of *discovery and identity resolution themselves*. NANDA's discovery is
+multi-source **by design** — a lean Index delegating to a quilt of registries —
+and corroboration is only *possible* because of it: the redundancy built for
+resilience doubles as an integrity check. This library turns that latent property
+into an active one, the concrete mechanism behind **accountable discovery** — a
+federated registry that is not merely decentralized but *auditable*.
+
+## Install
+
+```bash
+pip install sm-divergence                 # omission + endpoint/key checks (httpx only)
+pip install "sm-divergence[attestation]"  # + verified-DID checks (Ed25519/did:key)
+```
+
+## Quick start
+
+```python
+import asyncio
+from sm_divergence import check_once
+
+findings = asyncio.run(check_once(
+    ["https://registry-a.example", "https://registry-b.example"],
+    ["agent-1", "agent-2"],
+))
+for f in findings:
+    print(f.kind, f.agent_id, f.detail)
+    # endpoint agent-1 {'field': 'endpoint',
+    #                   'values': {'https://registry-a.example': 'https://real.example',
+    #                              'https://registry-b.example': 'https://attacker.example'}}
+```
+
+Long-running? Keep a detector and route new findings to your alert sink — it
+deduplicates, so a persisting divergence fires your callback once:
+
+```python
+from sm_divergence import DivergenceDetector
+
+detector = DivergenceDetector(
+    ["https://registry-a.example", "https://registry-b.example"],
+    on_finding=lambda f: alert(f.kind, f.agent_id, f.detail),
+)
+await detector.check(watch_ids=my_agent_ids)   # call each poll cycle
+```
+
+## CLI
+
+```bash
+python -m sm_divergence check \
+    --registry https://registry-a.example \
+    --registry https://registry-b.example \
+    --watch agent-1 --watch agent-2
+```
+
+Exit **0** when the sources agree, **2** when any divergence is found (so a cron
+or CI step fails loudly), **1** on a usage error. Add `--json` for machine
+output, `--attestation` to also compare verified DIDs, `--nanda-index URL`
+beside `--registry URL` to corroborate a NANDA Index.
+
+## What it compares
+
+Every finding is `omission` (present on one source, positively absent on another)
+or the name of a view field whose values disagree. The detail is uniform:
+`{"field": <name>, "values": {source: value}}` (or `{"present_on", "missing_from"}`
+for omission), so a consumer parses findings the same way at every layer.
+
+| Kind | Meaning |
+| --- | --- |
+| `omission` | One source serves the id; another **positively** reports it absent (404 / soft-404). An *unreachable* source is excluded — a timeout is not a claim. |
+| `endpoint` | Discovery sources disagree on an agent's endpoint. |
+| `did` | Discovery sources with a **verified** attestation disagree on the key. One valid record + one forged one is *not* a disagreement — only proven DIDs count. |
+| `key` | Identity sources (DID methods) disagree on the agent's verification key. |
+| `agent_equivocation` | The agent's *own key* signed two different self-descriptions at the same `seq` — key compromise or a lying agent (the one finding about the agent, not a source). |
+| `stale_description` | A source serves a self-description behind the highest `seq` (replay / lag). |
+
+## Architecture — a kernel and its layers
+
+The primitive factors into a source-agnostic **kernel** and a **layer** per thing
+a middleman can be asked. Each layer supplies its own view and thin resolvers;
+the kernel is untouched.
+
+```
+sm-resolver  (dependency)  the source-agnostic kernel — Resolver[T], the View
+                           contract, diff_views, Corroborator, Finding
+sm_divergence/
+  discovery/   registry-integrity layer — RecordView + HttpByIdResolver (NEST)
+               + NandaIndexV2Resolver
+  identity/    key-consistency layer — DidView + DidKeyResolver / DidWebResolver
+               / UniversalResolverResolver + signed self-description
+```
+
+The kernel now lives in its own package,
+[`sm-resolver`](https://github.com/Sharathvc23/sm-resolver) — `sm-divergence` is
+the reference set of layers built on it. Everything below is re-exported from the
+top level, so `from sm_divergence import Corroborator, Finding, …` is unchanged.
+
+**Sources of different formats mix in one run.** A `Resolver` hides one source's
+wire format and normalizes its answer to the same view the diff understands:
+
+```python
+from sm_divergence import DivergenceDetector, HttpByIdResolver, NandaIndexV2Resolver
+
+await DivergenceDetector([
+    HttpByIdResolver("https://nest.example"),        # GET /api/agents/{id}
+    NandaIndexV2Resolver("https://index.example"),   # two-hop resolve → record
+]).check(["agent-1"])
+```
+
+**Identity layer** — catches a `did:web` (or a Universal Resolver) serving a
+different verification key than the agent's self-certifying `did:key` root, a
+`key` divergence (the identity analogue of a tampered endpoint):
+
+```python
+from sm_divergence import Corroborator, DidKeyResolver, DidWebResolver
+
+await Corroborator([
+    DidKeyResolver(did_for=lambda a: agent_did_key[a]),   # offline root of truth
+    DidWebResolver(did_for=lambda a: agent_did_web[a]),   # fetched, may be hijacked
+]).check(agent_ids)
+```
+
+**A new format or layer is a thin adapter** — a view with a `comparable()` and a
+`Resolver` that returns it; the generic `Corroborator` + `diff_views` do the rest:
+
+```python
+from collections.abc import Mapping
+from dataclasses import dataclass
+from sm_divergence import Corroborator
+
+@dataclass(frozen=True)
+class MyView:
+    field: str | None = None
+    def comparable(self) -> Mapping[str, str | None]:
+        return {"field": self.field}
+
+class MyResolver:
+    label = "src-a"
+    async def resolve(self, agent_id): ...   # -> (Status, MyView | None)
+
+await Corroborator([MyResolver(), ...]).check(agent_ids)
+```
+
+**Signed correspondence** — the same agent is a bare id on one registry, a URN
+locator on an Index, a `did:web` on a domain, and corroboration can't infer that
+these are the same agent. Instead of trusting a caller-supplied mapping, let the
+agent *sign* its own aliases + endpoints; verify offline and drive the resolvers
+from the verified names, so a source that disagrees is contradicting the agent's
+own signature:
+
+```python
+from sm_divergence import (
+    build_self_description, HttpDescriptionResolver, corroborate_descriptions,
+    signed_alias_for, DidWebResolver, AliasClosureResolver, binds_by_key,
+)
+
+# the agent signs (bumping seq on every re-issue), with its did:key's private key:
+bundle = build_self_description(
+    aliases={"web": "did:web:acme.org", "nanda": "urn:ai:…:acme"},
+    services={"discovery": "https://acme.example/agents/acme"},
+    private_key=agent_ed25519_private_bytes, seq=5,
+)
+
+# a consumer fetches the description from EVERY source and reconciles it —
+# omission / replay / agent-equivocation on the description itself become findings:
+recs = await corroborate_descriptions(
+    [HttpDescriptionResolver(s) for s in source_urls], ["acme"],
+)
+canonical = recs["acme"].canonical                       # None if the agent equivocates
+sds = {"acme": canonical} if canonical else {}
+
+# drive resolvers from the PROVEN aliases, with closure so a claimed alias that
+# doesn't bind back to the did:key contributes no claim (never a false divergence):
+web = DidWebResolver(did_for=signed_alias_for(sds, "web"))
+web = AliasClosureResolver(web, lambda a: sds[a].did if a in sds else None, binds_by_key)
+```
+
+> The kernel lives in [`sm-resolver`](https://github.com/Sharathvc23/sm-resolver);
+> `sm-divergence` is the reference layers built on it. The top-level public API is
+> unchanged.
+
+For verified-DID comparison over signed records shaped
+`{"record": {..., "did": "did:key:z…", "endpoint": …}, "sig": "<b64 ed25519 over JCS(record)>"}`,
+use the built-in adapter (needs the `attestation` extra):
+
+```python
+from sm_divergence import DivergenceDetector, signed_record_adapter
+DivergenceDetector(registries, adapter=signed_record_adapter())
+```
+
+## Related packages
+
+| Package | Role |
+| --- | --- |
+| [`sm-bridge`](https://github.com/Sharathvc23/sm-bridge) | NANDA-compatible registry endpoints + Quilt-style deltas — *produces* the multi-source surface this corroborates across. |
+| [`sm-chapter`](https://github.com/Sharathvc23/sm-chapter) | Minimal registry/discovery server — a natural *consumer* that runs a divergence check each cycle. |
+| [`sm-conformance`](https://github.com/Sharathvc23/sm-conformance) | The shared Ed25519 / JCS signing convention this library's optional DID check verifies. |
+
+## Develop
+
+```bash
+make ci-local   # uv: sync → ruff → format → mypy --strict → pytest
+```
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+*First published: 2026-07-04 | Last modified: 2026-07-04*
+
+*Personal research contributions aligned with [Project NANDA](https://projectnanda.org) standards. [Stellarminds.ai](https://stellarminds.ai)*