induscode 0.1.0__py3-none-any.whl

induscode/capability_deck/bridge_ledger/__init__.py

@@ -0,0 +1,66 @@
+"""Bridge-ledger — public barrel for event-sourced MCP tool enrollment.
+
+Three concerns, one import site:
+
+- **Keys** (``.key``) — content-addressed and ULID :data:`BridgeKey` minting,
+  so re-enrolling the same external tool is an idempotent upsert.
+- **Ledger** (``.ledger``) — the immutable :class:`BridgeLedger` value and its
+  pure transitions: :func:`enroll_bridge_card` (upsert), :func:`retire` /
+  :func:`withdraw_server` (splice), each returning a new ledger folded by the
+  contract's :func:`reduce_ledger`.
+- **Network** (``.network``) — the side-effecting half:
+  :func:`attach_bridge_capabilities` mounting external MCP servers through the
+  framework's ``mount_protocol_bridge``, adapting the returned ``ToolBox``
+  into ``AgentTool``-shaped capabilities, and enrolling them into a ledger
+  (wholesale mount failure surfaces as a ``bridge`` :class:`DeckFault` on the
+  :class:`AttachResult`, never raised); :func:`detach_bridge` withdrawing a
+  server set and best-effort tearing the fleet down.
+
+The frozen shapes (:data:`BridgeKey`, :class:`BridgeEntry`,
+:class:`LedgerSnapshot`, :func:`reduce_ledger`) continue to live in the deck
+contract; this module re-exports the behavior that operates on them.
+"""
+
+from __future__ import annotations
+
+from .key import bridge_content_key, bridge_ulid_key, qualify_bridge_name
+from .ledger import (
+    BridgeLedger,
+    EnrollRequest,
+    bridge_ledger_from_log,
+    empty_bridge_ledger,
+    enroll_bridge_card,
+    live_capabilities,
+    live_capabilities_for_server,
+    retire,
+    withdraw_server,
+)
+from .network import (
+    AttachResult,
+    attach_bridge_capabilities,
+    bridge_box_to_capabilities,
+    bridge_capability_card,
+    bridge_config,
+    detach_bridge,
+)
+
+__all__ = [
+    "AttachResult",
+    "BridgeLedger",
+    "EnrollRequest",
+    "attach_bridge_capabilities",
+    "bridge_box_to_capabilities",
+    "bridge_capability_card",
+    "bridge_config",
+    "bridge_content_key",
+    "bridge_ledger_from_log",
+    "bridge_ulid_key",
+    "detach_bridge",
+    "empty_bridge_ledger",
+    "enroll_bridge_card",
+    "live_capabilities",
+    "live_capabilities_for_server",
+    "qualify_bridge_name",
+    "retire",
+    "withdraw_server",
+]

induscode/capability_deck/bridge_ledger/key.py

@@ -0,0 +1,181 @@
+"""Bridge-key minting — stable identifiers for enrolled MCP capabilities.
+
+An enrolled bridge capability needs a key that is *the same* across sessions
+for the same external tool, so re-enrolling is an idempotent upsert rather
+than an accumulating duplicate. The catalog already settled this policy in the
+contract: a :data:`BridgeKey` is "a content hash of the qualified
+``<server>__<tool>`` name (and its schema) or a fresh ULID" — keyed by the
+capability's *identity*, never by a working-directory digest.
+
+This module implements both halves of that policy and nothing else:
+
+- :func:`bridge_content_key` — the default. A deterministic digest of the
+  qualified name plus the canonicalized parameter schema. Two enrollments of
+  the same remote tool (same name, same schema) collapse to one key, so the
+  ledger upsert is naturally idempotent and the live set never duplicates a
+  tool just because a server reconnected.
+- :func:`bridge_ulid_key` — an opt-in, monotonic, time-sortable ULID for the
+  rare case a caller wants every enrollment to be a distinct event (e.g. an
+  ephemeral, per-invocation graft) rather than a deduplicated identity.
+
+Both return a branded :data:`BridgeKey`; neither touches the filesystem, the
+clock-as-state, or any shared mutable value.
+
+Port note — canonical-JSON parity with the TS lineage
+-----------------------------------------------------
+The content key must hash the same bytes the TS ``canonicalize`` produced, or
+keys minted by the two runtimes diverge (analysis 03 risk 9). The decisions:
+
+- **Objects**: keys sorted by UTF-16 code units (the TS ``a < b`` string
+  comparison), serialized ``"key":value`` with no whitespace. Entries whose
+  value is ``None`` are **dropped** — the Python stand-in for the TS filter
+  on ``undefined``-valued entries. (TS kept JSON ``null`` values; Python
+  cannot distinguish an in-memory "absent" from a JSON ``null`` once both are
+  ``None``, so dict-entry ``None`` is read as *absent*, exactly where — and
+  only where — TS dropped ``undefined``.)
+- **Arrays**: order preserved (it is semantic in JSON Schema, e.g.
+  ``required`` / ``enum``); ``None`` *elements* serialize as ``null`` — TS
+  rendered both ``null`` and ``undefined`` array elements as ``"null"``.
+- **Strings**: ``json.dumps(..., ensure_ascii=False)`` — matches
+  ``JSON.stringify`` escaping (quote/backslash/control characters escaped,
+  non-ASCII left raw).
+- **Numbers**: integral floats print without the trailing ``.0`` (JS has one
+  number type: ``1.0`` stringifies as ``"1"``); non-finite floats print as
+  ``null`` (``JSON.stringify(NaN)`` → ``"null"``).
+- **Everything non-JSON** (functions, arbitrary objects) prints as ``null``,
+  mirroring ``JSON.stringify(value) ?? "null"`` on unserializable values.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from collections.abc import Mapping, Sequence
+from hashlib import sha256
+
+from indusagi.interop import QUALIFIER
+from ulid import ULID
+from ulid import constants as _ulid_constants
+
+from ..contract import BridgeKey, Schema, bridge_key
+
+__all__ = [
+    "bridge_content_key",
+    "bridge_ulid_key",
+    "qualify_bridge_name",
+]
+
+
+def qualify_bridge_name(server: str, tool: str) -> str:
+    """The qualified, collision-free name the model sees for a remote tool —
+    ``"<server>__<tool>"``, using the framework's bridge :data:`QUALIFIER`.
+
+    The protocol bridge already stamps this exact form onto each grafted
+    tool's descriptor; we recompute it here only so a key can be minted
+    *before* a descriptor is in hand (e.g. from a ``RemoteToolRef``-shaped
+    pair).
+
+    :param server: the owning MCP server's id
+    :param tool: the remote tool's own (unqualified) name
+    """
+    return f"{server}{QUALIFIER}{tool}"
+
+
+def _canonical_scalar(value: object) -> str:
+    """Serialize one JSON scalar the way ``JSON.stringify`` would (see the
+    module docstring for the number/None decisions)."""
+    if value is None:
+        return "null"
+    if isinstance(value, bool):  # before int: bool is an int subclass
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        if value != value or value in (float("inf"), float("-inf")):
+            return "null"  # JSON.stringify(NaN/Infinity) -> "null"
+        if value.is_integer() and abs(value) < 1e21:
+            return str(int(value))  # JS prints 1.0 as "1"
+        return json.dumps(value)
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    # Unserializable (the TS `JSON.stringify(value) ?? "null"` fallback).
+    return "null"
+
+
+def _canonicalize(value: object) -> str:
+    """Stably serialize a parameter schema so two structurally-equal schemas
+    hash to the same string regardless of key insertion order.
+
+    A plain ``json.dumps`` of an unsorted mapping is order-sensitive:
+    ``{a,b}`` and ``{b,a}`` would digest differently even though they describe
+    the same parameters. This walks the value and sorts every object's keys
+    (by UTF-16 code units, matching the TS string comparison), yielding a
+    canonical form. Arrays keep their order (it is semantic in JSON Schema,
+    e.g. ``required``/``enum``). Mapping entries whose value is ``None`` are
+    dropped — the stand-in for the TS ``undefined`` filter.
+
+    :param value: the schema (or any JSON-ish value) to canonicalize
+    """
+    if isinstance(value, Mapping):
+        kept = [(str(k), v) for k, v in value.items() if v is not None]
+        kept.sort(key=lambda kv: kv[0].encode("utf-16-be"))
+        entries = (
+            f"{json.dumps(k, ensure_ascii=False)}:{_canonicalize(v)}" for k, v in kept
+        )
+        return "{" + ",".join(entries) + "}"
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        return "[" + ",".join(_canonicalize(item) for item in value) + "]"
+    return _canonical_scalar(value)
+
+
+def bridge_content_key(
+    server: str,
+    tool: str,
+    parameters: Schema | None = None,
+) -> BridgeKey:
+    """Mint a content-addressed :data:`BridgeKey` from a remote tool's
+    identity.
+
+    The digest is taken over the qualified ``<server>__<tool>`` name and the
+    canonicalized parameter schema, so the key is a pure function of *what the
+    tool is*. Enrolling the same tool twice yields the same key — the ledger
+    upsert deduplicates it — while a tool whose schema changed yields a new
+    key, correctly surfacing it as a distinct capability.
+
+    :param server: the owning MCP server's id
+    :param tool: the remote tool's own (unqualified) name
+    :param parameters: the tool's parameter schema (a raw JSON-schema mapping)
+    """
+    qualified = qualify_bridge_name(server, tool)
+    schema_part = "" if parameters is None else _canonicalize(parameters)
+    digest = sha256()
+    digest.update(qualified.encode("utf-8"))
+    digest.update(b" ")  # domain separator so name|schema cannot collide with name+schema
+    digest.update(schema_part.encode("utf-8"))
+    return bridge_key(f"bk_{digest.hexdigest()[:32]}")
+
+
+def bridge_ulid_key(monotonic: bool = True) -> BridgeKey:
+    """Mint a fresh, time-sortable :data:`BridgeKey` as a ULID.
+
+    Use when each enrollment must be a *distinct* event rather than a
+    deduplicated identity — for instance an ephemeral, per-invocation graft,
+    or when two differently-configured connections to the same server should
+    each get their own live entry. The ULID is monotonic within a process so
+    ordering is stable.
+
+    :param monotonic: when ``True`` (default) use ``python-ulid``'s
+        process-monotonic provider so keys minted in the same millisecond
+        remain strictly increasing (the TS ``monotonicFactory()``); pass
+        ``False`` for a plain, independent ULID built from a fresh timestamp
+        and randomness.
+    """
+    if monotonic:
+        # python-ulid's shared ValueProvider increments the randomness when two
+        # ULIDs land in the same millisecond — process-monotonic by default.
+        return bridge_key(f"bk_{ULID()}")
+    raw = (time.time_ns() // 1_000_000).to_bytes(
+        _ulid_constants.TIMESTAMP_LEN, "big"
+    ) + os.urandom(_ulid_constants.RANDOMNESS_LEN)
+    return bridge_key(f"bk_{ULID(raw)}")

induscode/capability_deck/bridge_ledger/ledger.py

@@ -0,0 +1,276 @@
+"""The immutable bridge ledger — event-sourced enrollment of MCP capabilities.
+
+MCP tools are grafted in and pulled out over a session's life: a server
+connects and contributes a handful of tools, another disconnects, the same
+server reconnects after a hot-reload. Rather than mutate a shared module-level
+list of live tools (which makes "who's enrolled right now" a function of call
+order and hides every past change), enrollment here is an **append-only event
+log** folded into a **derived snapshot**.
+
+- :class:`BridgeLedger` is a plain immutable value: the ordered
+  :class:`BridgeEntry` log, its already-folded :class:`LedgerSnapshot`, and
+  the next sequence number to stamp.
+- Every mutation (:func:`enroll_bridge_card`, :func:`retire`,
+  :func:`withdraw_server`) returns a *new* ledger; the input is never touched.
+  ``enroll`` is an upsert (re-enrolling a key replaces its entry), ``retire``
+  is a splice (the keyed entry is removed from the live view).
+- The live view is produced solely by the contract's pure
+  :func:`reduce_ledger` fold, so the snapshot can never drift from the log.
+
+The log is the source of truth; the snapshot is a cache of its fold. Because
+both live on the value, callers read ``ledger.snapshot.live`` directly and
+never re-reduce by hand.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from ..contract import (
+    AnyCapability,
+    BridgeEntry,
+    BridgeKey,
+    LedgerSnapshot,
+    reduce_ledger,
+)
+from .key import bridge_content_key
+
+__all__ = [
+    "BridgeLedger",
+    "EnrollRequest",
+    "bridge_ledger_from_log",
+    "empty_bridge_ledger",
+    "enroll_bridge_card",
+    "live_capabilities",
+    "live_capabilities_for_server",
+    "retire",
+    "withdraw_server",
+]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BridgeLedger:
+    """An immutable, event-sourced view of MCP tool enrollment.
+
+    Holds the append-only :class:`BridgeEntry` log, the
+    :class:`LedgerSnapshot` that is its current fold, and the sequence number
+    the next appended entry will carry. Treat every instance as frozen: the
+    enroll/retire/withdraw helpers derive a new ledger rather than editing
+    this one in place.
+    """
+
+    # The append-only enrollment event log, in append order.
+    log: tuple[BridgeEntry, ...]
+    # The current fold of `log` — the live capabilities and per-server counts.
+    snapshot: LedgerSnapshot
+    # The sequence number the next appended `BridgeEntry` will carry.
+    next_seq: int
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class EnrollRequest:
+    """The fields an enrollment supplies; the ledger stamps ``op``, ``seq``,
+    and ``at``.
+
+    A caller names the capability, the owning server, and optionally a
+    pre-minted :data:`BridgeKey`; when the key is omitted it is
+    content-addressed from the capability's identity so re-enrolling the same
+    tool is idempotent.
+    """
+
+    # The grafted capability to enroll (its `name` is the qualified tool name).
+    capability: AnyCapability
+    # Id of the external MCP server that owns the capability.
+    server: str
+    # Optional explicit key; content-addressed from the capability when omitted.
+    key: BridgeKey | None = None
+
+
+def _now_iso() -> str:
+    """An ISO-8601 UTC timestamp in the TS ``Date.toISOString()`` form."""
+    return (
+        datetime.now(timezone.utc)
+        .isoformat(timespec="milliseconds")
+        .replace("+00:00", "Z")
+    )
+
+
+def empty_bridge_ledger() -> BridgeLedger:
+    """An empty ledger: no events, an empty live view, sequence numbering at 1."""
+    return BridgeLedger(log=(), snapshot=reduce_ledger(()), next_seq=1)
+
+
+def bridge_ledger_from_log(log: Sequence[BridgeEntry]) -> BridgeLedger:
+    """Rebuild a ledger value from a persisted event log.
+
+    The log is authoritative, so a ledger is fully reconstructable from it:
+    fold it for the snapshot and resume sequence numbering one past its
+    high-water mark. Use when rehydrating enrollment state across a restart.
+
+    :param log: the persisted append-only entries, in any order (sorted on fold)
+    """
+    snapshot = reduce_ledger(log)
+    high_water = 0
+    for entry in log:
+        if entry.seq > high_water:
+            high_water = entry.seq
+    return BridgeLedger(log=tuple(log), snapshot=snapshot, next_seq=high_water + 1)
+
+
+def _resolve_key(req: EnrollRequest) -> BridgeKey:
+    """Resolve the key for an :class:`EnrollRequest`: the caller's explicit
+    key, or a content key derived from the capability's identity."""
+    if req.key is not None:
+        return req.key
+    cap = req.capability
+    # `cap.name` is already the qualified "<server>__<tool>" the bridge stamped
+    # on; pairing it with the schema makes the key a pure function of the
+    # tool's shape.
+    return bridge_content_key(req.server, cap.name, cap.parameters)
+
+
+def enroll_bridge_card(
+    ledger: BridgeLedger,
+    req: EnrollRequest,
+    at: str | None = None,
+) -> BridgeLedger:
+    """Append an ``enroll`` event and return the resulting ledger.
+
+    The graft is an **upsert**: the appended entry carries a
+    :data:`BridgeKey`, and because :func:`reduce_ledger` lets a later sequence
+    win on a repeated key, a re-enrollment of the same tool transparently
+    replaces its prior live entry rather than duplicating it. The input ledger
+    is not mutated.
+
+    :param ledger: the current ledger (left untouched)
+    :param req: the capability + server to enroll, with an optional explicit key
+    :param at: enrollment timestamp; defaults to now (ISO-8601)
+    """
+    key = _resolve_key(req)
+    entry = BridgeEntry(
+        op="enroll",
+        key=key,
+        server=req.server,
+        capability=req.capability,
+        seq=ledger.next_seq,
+        at=at if at is not None else _now_iso(),
+    )
+    return _append_entry(ledger, entry)
+
+
+def retire(
+    ledger: BridgeLedger,
+    key: BridgeKey,
+    server: str,
+    at: str | None = None,
+) -> BridgeLedger:
+    """Append a ``retire`` event for one capability and return the resulting
+    ledger.
+
+    The withdrawal is a **splice**: the appended ``retire`` entry names the
+    key, and the fold drops that key from the live view. Retiring an unknown
+    or already-retired key is a harmless no-op in the live set (the event is
+    still recorded for the audit trail). The input ledger is not mutated.
+
+    :param ledger: the current ledger (left untouched)
+    :param key: the stable key of the capability to withdraw
+    :param server: the owning server id, recorded on the event
+    :param at: retirement timestamp; defaults to now (ISO-8601)
+    """
+    entry = BridgeEntry(
+        op="retire",
+        key=key,
+        server=server,
+        seq=ledger.next_seq,
+        at=at if at is not None else _now_iso(),
+    )
+    return _append_entry(ledger, entry)
+
+
+def withdraw_server(
+    ledger: BridgeLedger,
+    server: str,
+    at: str | None = None,
+) -> BridgeLedger:
+    """Retire every capability a given server currently has live, in one batch.
+
+    Appends one ``retire`` event per live key owned by the server — the
+    disconnect counterpart to grafting a whole server's tool set. Servers with
+    nothing live yield the ledger unchanged. The input ledger is not mutated.
+
+    :param ledger: the current ledger (left untouched)
+    :param server: the server whose live capabilities should all be withdrawn
+    :param at: retirement timestamp applied to every event; defaults to now
+    """
+    owned = _live_keys_for_server(ledger, server)
+    if not owned:
+        return ledger
+    stamp = at if at is not None else _now_iso()
+    seq = ledger.next_seq
+    events: list[BridgeEntry] = []
+    for key in owned:
+        events.append(BridgeEntry(op="retire", key=key, server=server, seq=seq, at=stamp))
+        seq += 1
+    log = (*ledger.log, *events)
+    return BridgeLedger(log=log, snapshot=reduce_ledger(log), next_seq=seq)
+
+
+def live_capabilities_for_server(
+    ledger: BridgeLedger, server: str
+) -> list[AnyCapability]:
+    """Read the live capabilities a single server currently contributes.
+
+    Pure projection over the snapshot; the per-key→server association is
+    recovered from the log (each live key's last-touching server). Handy for
+    status panels and for :func:`withdraw_server`'s batch retirement.
+
+    :param ledger: the ledger to read
+    :param server: the server id to filter by
+    """
+    out: list[AnyCapability] = []
+    for key in _live_keys_for_server(ledger, server):
+        cap = ledger.snapshot.live.get(key)
+        if cap is not None:
+            out.append(cap)
+    return out
+
+
+def live_capabilities(ledger: BridgeLedger) -> list[AnyCapability]:
+    """The flat list of every live capability, in stable iteration order.
+
+    What a deck assembler grafts onto the static catalog before handing the
+    conductor its ``options.tools``.
+    """
+    return list(ledger.snapshot.live.values())
+
+
+# ---------------------------------------------------------------------------
+# internals
+# ---------------------------------------------------------------------------
+
+
+def _append_entry(ledger: BridgeLedger, entry: BridgeEntry) -> BridgeLedger:
+    """Append one stamped entry and re-fold; the single mutation primitive."""
+    log = (*ledger.log, entry)
+    return BridgeLedger(log=log, snapshot=reduce_ledger(log), next_seq=entry.seq + 1)
+
+
+def _live_keys_for_server(ledger: BridgeLedger, server: str) -> list[BridgeKey]:
+    """The live keys a server owns, derived from the log: a key is the
+    server's when the server's last touch on that key is the entry the fold
+    settled on. We map each key to the server of its highest-seq entry, then
+    keep the live ones."""
+    last_server: dict[BridgeKey, str] = {}
+    last_seq: dict[BridgeKey, int] = {}
+    for entry in ledger.log:
+        seen = last_seq.get(entry.key)
+        if seen is None or entry.seq >= seen:
+            last_seq[entry.key] = entry.seq
+            last_server[entry.key] = entry.server
+    out: list[BridgeKey] = []
+    for key in ledger.snapshot.live:
+        if last_server.get(key) == server:
+            out.append(key)
+    return out