sm-resolver 0.1.0__py3-none-any.whl

sm_resolver/__init__.py

@@ -0,0 +1,39 @@
+"""sm-resolver — the source-agnostic corroboration kernel.
+
+A tiny, dependency-free kernel for detecting when independent sources disagree
+about the same subject. It is the machinery under cross-registry / cross-method
+divergence detection, factored out so any layer can reuse it:
+
+- ``View`` — the contract a claim implements (``comparable() → named fields``).
+- ``Resolver[T]`` — a per-source adapter: canonical id → ``(Status, View)``.
+- ``diff_views`` — the pure diff: per-source claims → ``Finding`` list
+  (``omission`` + one per disagreeing field). It never learns its layer.
+- ``Corroborator`` — resolve every source, diff, emit (deduped).
+
+A consumer supplies a view type (its fields are what gets compared) and thin
+per-source resolvers; the kernel does the rest, identically across discovery,
+identity, capability, or evidence layers. See ``sm-divergence`` for the reference
+layers (registries, DID methods) built on this.
+
+Zero runtime dependencies.
+"""
+
+from .corroborate import Corroborator, OnFinding
+from .diff import diff_views
+from .models import OMISSION, Finding
+from .resolver import Resolver, Status
+from .view import View, ViewT
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "OMISSION",
+    "Corroborator",
+    "Finding",
+    "OnFinding",
+    "Resolver",
+    "Status",
+    "View",
+    "ViewT",
+    "diff_views",
+]

sm_resolver/corroborate.py

@@ -0,0 +1,77 @@
+"""Generic orchestration: resolve every watched id against every source, diff,
+and hand new findings to a callback. Layer-agnostic — a thin adapter for any
+source set (e.g. two NANDA Indexes, or a NEST + an Index) drives this directly
+with its own ``Resolver`` instances; no discovery internals required.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Generic
+
+from .diff import diff_views
+from .models import Finding
+from .resolver import Resolver
+from .view import ViewT
+
+OnFinding = Callable[[Finding], None]
+
+
+class Corroborator(Generic[ViewT]):
+    """Corroborate a set of sources for a watch set.
+
+    Give it two or more ``Resolver`` instances; each ``check`` asks all of them
+    the same by-id questions and reports any disagreement. Fewer than two
+    sources → nothing to corroborate → no-op. Sources are deduped by ``label``.
+
+    ``on_finding`` fires once per distinct finding across the corroborator's
+    lifetime (deduped by fingerprint); ``check`` always returns ALL current
+    findings. Never raises.
+    """
+
+    def __init__(self, resolvers: Iterable[Resolver[ViewT]], *, on_finding: OnFinding | None = None) -> None:
+        deduped: list[Resolver[ViewT]] = []
+        seen: set[str] = set()
+        for r in resolvers:
+            if r.label in seen:
+                continue
+            seen.add(r.label)
+            deduped.append(r)
+        self.resolvers = deduped
+        self.on_finding = on_finding
+        self._emitted: set[str] = set()
+
+    @property
+    def labels(self) -> list[str]:
+        return [r.label for r in self.resolvers]
+
+    async def check(self, watch_ids: Iterable[str]) -> list[Finding]:
+        ids = sorted(set(watch_ids))
+        if len(self.resolvers) < 2 or not ids:
+            return []
+
+        views: dict[str, dict[str, ViewT | None]] = {}
+        for resolver in self.resolvers:
+            per_source: dict[str, ViewT | None] = {}
+            for aid in ids:
+                try:
+                    status, view = await resolver.resolve(aid)
+                except Exception:
+                    status, view = "error", None
+                if status == "error":
+                    continue  # unreachable is not a claim
+                per_source[aid] = view
+            views[resolver.label] = per_source
+
+        findings = diff_views(views, ids)
+        if self.on_finding is not None:
+            for f in findings:
+                fp = f.fingerprint()
+                if fp in self._emitted:
+                    continue
+                self._emitted.add(fp)
+                try:
+                    self.on_finding(f)
+                except Exception:
+                    pass
+        return findings

sm_resolver/diff.py

@@ -0,0 +1,71 @@
+"""The pure diff — no I/O, generic over the view type. Given each source's view
+of each id, find the disagreements. This is the whole idea; everything else is
+plumbing to feed it, and it never learns what layer it is serving.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+
+from .models import OMISSION, Finding
+from .view import ViewT
+
+
+def diff_views(
+    views: Mapping[str, Mapping[str, ViewT | None]],
+    watch_ids: Iterable[str],
+) -> list[Finding]:
+    """Compare what every source claims about each watched id.
+
+    ``views[source][agent_id]`` is:
+      - a view — the source served a claim;
+      - ``None`` — the source POSITIVELY reports the id absent (a 404);
+      - simply *missing from the inner mapping* — the source made no claim
+        (unreachable). A silent source is never present or absent: a timeout is
+        not evidence.
+
+    Findings, per id:
+      - ``omission``  — present on ≥1 source AND confirmed-absent on ≥1 other.
+      - one per view field (``endpoint``, ``did``, ``key``, …) whose non-``None``
+        values disagree across the sources that served it.
+
+    Deterministic and side-effect free; never raises.
+    """
+    findings: list[Finding] = []
+    for aid in sorted(set(watch_ids)):
+        present: dict[str, Mapping[str, str | None]] = {}
+        confirmed_absent: list[str] = []
+        for source, per_source in views.items():
+            if aid not in per_source:
+                continue  # no claim — unreachable, not an omission
+            claim = per_source[aid]
+            if claim is None:
+                confirmed_absent.append(source)
+            else:
+                present[source] = claim.comparable()
+
+        if present and confirmed_absent:
+            findings.append(
+                Finding(
+                    OMISSION,
+                    aid,
+                    {"present_on": sorted(present), "missing_from": sorted(confirmed_absent)},
+                )
+            )
+
+        field_names: list[str] = []
+        for comparable in present.values():
+            for name in comparable:
+                if name not in field_names:
+                    field_names.append(name)
+
+        for name in field_names:
+            values: dict[str, str] = {}
+            for source, comparable in present.items():
+                value = comparable.get(name)
+                if value is not None:
+                    values[source] = value
+            if len(set(values.values())) > 1:
+                findings.append(Finding(name, aid, {"field": name, "values": dict(sorted(values.items()))}))
+
+    return findings

sm_resolver/models.py

@@ -0,0 +1,38 @@
+"""The finding — what disagreement was found. Layer-agnostic."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+# The universal divergence kind (present on one source, confirmed-absent on
+# another). Field-level kinds are named after the view field that diverged
+# (e.g. "endpoint", "did", "key") and are supplied by the view, not fixed here.
+OMISSION = "omission"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One divergence about one subject across the compared sources.
+
+    ``kind`` is ``omission`` or the name of a view field that diverged.
+    ``detail`` carries the contradicting per-source claims. For ``omission`` it
+    is ``{present_on, missing_from}``; for a field divergence it is
+    ``{field, values}`` (``values`` keyed by source label) — one uniform shape
+    across every layer, so any consumer parses findings the same way.
+    """
+
+    kind: str
+    agent_id: str
+    detail: dict[str, object] = field(default_factory=dict)
+
+    def fingerprint(self) -> str:
+        """A stable key for deduping a persisting finding across repeated
+        checks — same disagreement, same fingerprint."""
+        return json.dumps(
+            {"kind": self.kind, "agent_id": self.agent_id, "detail": self.detail},
+            sort_keys=True,
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return {"kind": self.kind, "agent_id": self.agent_id, "detail": self.detail}

sm_resolver/resolver.py

@@ -0,0 +1,37 @@
+"""The Resolver protocol — one registry/source, one way of being asked.
+
+Sources do not share a wire format: a NEST server answers ``GET /api/agents/{id}``;
+a NANDA Index answers a two-hop resolve; a DID method resolves a document; a
+DNS-AID zone answers a TXT lookup. A ``Resolver`` hides that difference: given a
+canonical agent id it performs *that* source's query, applies *that* source's
+native verification, and normalizes the answer to ``(Status, View)`` — so the
+diff downstream is untouched by format heterogeneity. This is the seam a thin
+per-source adapter (e.g. a NANDA Index adapter) implements.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Protocol, TypeVar
+
+from .view import View
+
+# One source's claim about one id: served / positively-absent / no-claim.
+Status = Literal["present", "absent", "error"]
+
+# Covariant: a Resolver only ever PRODUCES its view type, so Resolver[Sub] is
+# usable where Resolver[Base] is expected.
+T_co = TypeVar("T_co", bound=View, covariant=True)
+
+
+class Resolver(Protocol[T_co]):
+    """Resolves a canonical agent id to one source's normalized claim.
+
+    ``label`` names the source in findings. ``resolve`` MUST NOT raise — an
+    unreachable or unparseable source is the ``"error"`` claim (no claim),
+    never a false ``"absent"``.
+    """
+
+    @property
+    def label(self) -> str: ...
+
+    async def resolve(self, agent_id: str) -> tuple[Status, T_co | None]: ...

sm_resolver/view.py

@@ -0,0 +1,28 @@
+"""The comparable-view contract — the one thing a layer must provide.
+
+A view is any object that reduces itself to a set of named string fields via
+``comparable()``. Those fields ARE what corroboration compares: each field whose
+value differs across sources becomes a divergence finding named for that field;
+a field value of ``None`` never participates (an unverifiable value is not a
+disagreement). Omission (present vs confirmed-absent) is universal and needs no
+field.
+
+This is the whole contract an adapter author implements — return a view type
+from a ``Resolver``, give it a ``comparable()``, and the generic diff does the
+rest, identically across discovery, identity, capability, and evidence layers.
+The discovery layer's ``RecordView`` is just the first implementation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Protocol, TypeVar
+
+
+class View(Protocol):
+    """A claim reduced to named, comparable string fields."""
+
+    def comparable(self) -> Mapping[str, str | None]: ...
+
+
+ViewT = TypeVar("ViewT", bound=View)

sm_resolver-0.1.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: sm-resolver
+Version: 0.1.0
+Summary: The source-agnostic corroboration kernel — Resolver[T], the View contract, a pure diff, and the Corroborator. Zero runtime dependencies.
+Project-URL: Homepage, https://github.com/Sharathvc23/sm-resolver
+Project-URL: Spec, https://github.com/Sharathvc23/sm-resolver/blob/main/SPEC.md
+Project-URL: Whitepaper, https://github.com/Sharathvc23/sm-resolver/blob/main/WHITEPAPER.md
+Author: Sharath (Stellarminds)
+License: MIT
+License-File: LICENSE
+Keywords: accountability,ai-agents,corroboration,divergence,nanda,resolver
+Requires-Python: >=3.11
+Provides-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-resolver — the corroboration kernel
+
+**A tiny, dependency-free kernel for detecting when independent sources disagree
+about the same subject.** Point it at two or more sources, ask them the same
+question, and it reports any disagreement. It is the machinery under
+cross-registry / cross-method divergence detection, factored out so any layer can
+reuse it.
+
+Four pieces, and only the resolvers know a wire format:
+
+- **`View`** — the contract a claim implements: `comparable() → {field: value}`.
+  Those fields are what gets compared; a `None` value never participates.
+- **`Resolver[T]`** — a per-source adapter: a canonical id → `(Status, View)`.
+  It hides one source's format (an HTTP GET, a DID resolve, a DNS lookup) and
+  MUST NOT raise — an unreachable source is `error` (no claim), never a false
+  `absent`.
+- **`diff_views`** — the pure diff: per-source claims → `Finding` list. It emits
+  `omission` (present on one source, positively absent on another) and one
+  finding per view field whose values disagree. It never learns its layer.
+- **`Corroborator`** — resolve every source, diff, and emit new findings once
+  (deduped). Fewer than two sources → no-op.
+
+## Install
+
+```bash
+pip install sm-resolver        # zero runtime dependencies
+```
+
+## Use
+
+Supply a view (its fields are what you compare) and a thin resolver per source:
+
+```python
+import asyncio
+from collections.abc import Mapping
+from dataclasses import dataclass
+from sm_resolver import Corroborator, Status
+
+@dataclass(frozen=True)
+class RecordView:                       # your layer's view
+    endpoint: str | None = None
+    def comparable(self) -> Mapping[str, str | None]:
+        return {"endpoint": self.endpoint}
+
+class MyResolver:                       # your thin per-source adapter
+    def __init__(self, label): self.label = label
+    async def resolve(self, agent_id) -> tuple[Status, RecordView | None]:
+        ...                             # query this source; normalize to RecordView
+
+findings = asyncio.run(
+    Corroborator([MyResolver("a"), MyResolver("b")]).check(["agent-1"])
+)
+for f in findings:
+    print(f.kind, f.agent_id, f.detail)
+    # endpoint agent-1 {'field': 'endpoint', 'values': {'a': 'https://real', 'b': 'https://evil'}}
+```
+
+Long-running? Pass `on_finding=` — it fires once per distinct finding across the
+corroborator's lifetime.
+
+## Who uses it
+
+[`sm-divergence`](https://github.com/Sharathvc23/sm-divergence) builds the
+reference layers on this kernel: a **discovery** layer (registries — NEST, the
+NANDA Index) and an **identity** layer (DID methods — `did:key`, `did:web`,
+Universal Resolver), each supplying its own view and thin resolvers. Capability
+and evidence layers are the same shape.
+
+## Design rules
+
+- **A timeout is not a claim.** An unreachable or erroring source is excluded,
+  never counted as an omission.
+- **Only present, comparable values disagree.** A `None` field contributes
+  nothing — an unverifiable value is not a disagreement.
+- **The diff stays pure and generic** — deterministic, no I/O, never raises,
+  never learns its layer. All I/O lives in the resolvers.
+
+## 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)*

sm_resolver-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+sm_resolver/__init__.py,sha256=iOjfO6iAufXEbjrdabmKXEx3GNfIJw4X69NSSWbZoa8,1347
+sm_resolver/corroborate.py,sha256=JuF6rhxYzM_Cwbze3N4YUp0SX17bWRlfJKuNAqAHlug,2739
+sm_resolver/diff.py,sha256=sXS2rQCt3yqqHNbJFL4yRFI9Z_DmKVW_M61ALTqVWHI,2640
+sm_resolver/models.py,sha256=E2SlnHIok2XFaKeNEswectY8l9royeRlEJK80MudcYA,1440
+sm_resolver/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sm_resolver/resolver.py,sha256=g825OkEQ8cTnpMPBFkcVYRQBnFTEfh-15CdckdCnvV4,1444
+sm_resolver/view.py,sha256=oxIkWKM5Jk08ZO4TTdMSGZAcjbBesnuttRI5tFTI5mM,1082
+sm_resolver-0.1.0.dist-info/METADATA,sha256=9xVcErd1POy9Y2R5R3vHv99sVYToQFLNdG3--B4htOc,4326
+sm_resolver-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+sm_resolver-0.1.0.dist-info/licenses/LICENSE,sha256=mo4bEHboox6Cvk1DuRHhTstvfo1NRFPs5QqRfvrufBc,1072
+sm_resolver-0.1.0.dist-info/RECORD,,

sm_resolver-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

sm_resolver-0.1.0.dist-info/licenses/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.