hypermind 0.11.0__py3-none-any.whl

hypermind/revocation.py

@@ -0,0 +1,270 @@
+"""Key revocation primitive — Certificate-Revocation-List (CRL) shape.
+
+Spec: ``docs/spec/18-revocation.md`` (v0.7).
+
+The federation-root operator publishes a signed ``RevocationList`` that
+enumerates kids that MUST NOT be trusted past their ``revoked_at_hlc``.
+Verifiers consult a pluggable ``RevocationStore`` while validating each
+``SignedStatement`` — any statement whose ``hlc >= entry.revoked_at_hlc``
+and whose ``issuer_kid`` matches a revoked entry is rejected with rule_id
+``HM-KEY-REVOKED-001``.
+
+Statements signed BEFORE the revocation point remain valid (replay-safety
+for historical claims). The revocation list itself is signed over its
+canonical CBOR encoding by the namespace-root keypair, and SHOULD be
+witness-cosigned and inserted into the transparency log so any auditor
+can independently verify a CRL was actually published (vs. an out-of-band
+forgery).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+import cbor2
+
+from hypermind.crypto.signing import (
+    Keypair,
+    verify_ed25519,
+)
+
+RevocationReason = Literal["compromise", "rotation", "operator_revoke"]
+_REVOCATION_REASONS: frozenset[str] = frozenset(("compromise", "rotation", "operator_revoke"))
+
+#: Domain-separation tag for the RevocationList signature preimage.
+#: Keeps a CRL signature unforgeable against a colliding statement-kind
+#: (per `domain.py` WF-DOMAIN refinement lemma).
+_DOMAIN_TAG = b"\x07hypermind-revocation-list-v1"
+
+
+@dataclass(frozen=True, slots=True)
+class RevocationEntry:
+    """Single revoked key.
+
+    `revoked_at_hlc` is the (logical_ms, counter) HLC pair past which any
+    statement signed by `kid` MUST be rejected. Statements with HLC
+    *strictly less than* the revocation point remain valid — this
+    preserves the historical record (they were signed by a then-trusted
+    key) while denying new traffic.
+    """
+
+    kid: bytes
+    revoked_at_hlc: tuple[int, int]
+    reason: RevocationReason
+    reason_detail: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.kid, (bytes, bytearray)) or len(self.kid) != 32:
+            raise ValueError("RevocationEntry.kid must be 32 bytes")
+        if (
+            not isinstance(self.revoked_at_hlc, tuple)
+            or len(self.revoked_at_hlc) != 2
+            or not all(isinstance(x, int) and x >= 0 for x in self.revoked_at_hlc)
+        ):
+            raise ValueError("RevocationEntry.revoked_at_hlc must be a (int>=0, int>=0) tuple")
+        if self.reason not in _REVOCATION_REASONS:
+            raise ValueError(
+                f"RevocationEntry.reason must be one of {sorted(_REVOCATION_REASONS)!r}; "
+                f"got {self.reason!r}"
+            )
+
+    def to_canonical(self) -> dict:
+        """Return the canonical-CBOR-friendly representation (sorted keys)."""
+        d: dict = {
+            "kid": bytes(self.kid),
+            "revoked_at_hlc": [self.revoked_at_hlc[0], self.revoked_at_hlc[1]],
+            "reason": self.reason,
+        }
+        if self.reason_detail is not None:
+            d["reason_detail"] = self.reason_detail
+        return d
+
+
+@dataclass(frozen=True, slots=True)
+class RevocationList:
+    """Signed list of revoked kids in a namespace.
+
+    The signature is computed by the namespace root keypair over
+    deterministic CBOR of (entries, issued_by, issued_at_hlc) prefixed by
+    a fixed domain-separation tag.
+
+    Per spec/18-revocation.md §12.3, the issued list SHOULD additionally
+    be witness-cosigned and submitted to the transparency log; that
+    cosigning is layered on top of `RevocationList` and lives in
+    `hypermind.knowledge.transparency`.
+    """
+
+    entries: tuple[RevocationEntry, ...]
+    issued_by: bytes
+    issued_at_hlc: tuple[int, int]
+    sig: bytes
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.entries, tuple):
+            raise TypeError("RevocationList.entries must be a tuple")
+        if not isinstance(self.issued_by, (bytes, bytearray)) or len(self.issued_by) != 32:
+            raise ValueError("RevocationList.issued_by must be a 32-byte kid")
+        if not isinstance(self.issued_at_hlc, tuple) or len(self.issued_at_hlc) != 2:
+            raise ValueError("RevocationList.issued_at_hlc must be a (int, int) tuple")
+
+    @staticmethod
+    def _signing_preimage(
+        entries: tuple[RevocationEntry, ...],
+        issued_by: bytes,
+        issued_at_hlc: tuple[int, int],
+    ) -> bytes:
+        body = {
+            "entries": [e.to_canonical() for e in entries],
+            "issued_by": bytes(issued_by),
+            "issued_at_hlc": [issued_at_hlc[0], issued_at_hlc[1]],
+        }
+        return _DOMAIN_TAG + cbor2.dumps(body, canonical=True)
+
+    @classmethod
+    def issue(
+        cls,
+        *,
+        entries: tuple[RevocationEntry, ...] | list[RevocationEntry],
+        issuer: Keypair,
+        issued_at_hlc: tuple[int, int],
+    ) -> RevocationList:
+        """Sign a fresh RevocationList from a list of entries."""
+        ents = tuple(entries)
+        # Reject duplicate kids — a CRL with two entries for the same kid
+        # is ambiguous (which `revoked_at_hlc` wins?). Operators should
+        # collapse duplicates before issuing.
+        seen: set[bytes] = set()
+        for e in ents:
+            if bytes(e.kid) in seen:
+                raise ValueError(f"duplicate kid in RevocationList: {bytes(e.kid).hex()[:16]}…")
+            seen.add(bytes(e.kid))
+
+        preimage = cls._signing_preimage(ents, issuer.kid, issued_at_hlc)
+        sig = issuer.sign(preimage)
+        return cls(
+            entries=ents,
+            issued_by=issuer.kid,
+            issued_at_hlc=issued_at_hlc,
+            sig=sig,
+        )
+
+    def verify(self, *, issuer_pk: bytes | None = None) -> bool:
+        """Verify the RevocationList signature against the issuer's pubkey.
+
+        For Ed25519 (v0.1 default for namespace-roots), `issuer_kid` IS
+        the public key and `issuer_pk` may be omitted. For composite
+        algorithms the caller MUST supply the full public key — the
+        revocation list does not currently carry the ML-DSA half on the
+        wire (a v0.8 follow-up if PQ namespace-roots prove necessary).
+        """
+        pk = issuer_pk if issuer_pk is not None else self.issued_by
+        if len(pk) < 32:
+            return False
+        preimage = self._signing_preimage(self.entries, self.issued_by, self.issued_at_hlc)
+        # If a 32-byte pk is supplied, treat as Ed25519. If composite is
+        # ever wired, dispatch via verify_signature(alg=…) here.
+        return verify_ed25519(pk[:32], self.sig, preimage)
+
+    def to_cbor(self) -> bytes:
+        """Canonical CBOR serialization for transport / storage."""
+        return cbor2.dumps(
+            {
+                "entries": [e.to_canonical() for e in self.entries],
+                "issued_by": bytes(self.issued_by),
+                "issued_at_hlc": [self.issued_at_hlc[0], self.issued_at_hlc[1]],
+                "sig": bytes(self.sig),
+            },
+            canonical=True,
+        )
+
+    @classmethod
+    def from_cbor(cls, raw: bytes, *, verify: bool = True) -> RevocationList:
+        """Parse a serialised RevocationList.
+
+        When ``verify=True`` (the default), the signature is verified before
+        returning. Pass ``verify=False`` only when the caller will explicitly
+        call ``.verify()`` immediately after (e.g. inside a custom store).
+        """
+        body = cbor2.loads(raw)
+        if not isinstance(body, dict):
+            raise ValueError("RevocationList CBOR must be a map")
+        entries = tuple(
+            RevocationEntry(
+                kid=bytes(e["kid"]),
+                revoked_at_hlc=(int(e["revoked_at_hlc"][0]), int(e["revoked_at_hlc"][1])),
+                reason=e["reason"],
+                reason_detail=e.get("reason_detail"),
+            )
+            for e in body["entries"]
+        )
+        crl = cls(
+            entries=entries,
+            issued_by=bytes(body["issued_by"]),
+            issued_at_hlc=(int(body["issued_at_hlc"][0]), int(body["issued_at_hlc"][1])),
+            sig=bytes(body["sig"]),
+        )
+        if verify and not crl.verify():
+            raise ValueError("RevocationList signature verification failed")
+        return crl
+
+
+# ----------------------------------------------------------------------- #
+# Pluggable revocation store
+# ----------------------------------------------------------------------- #
+
+
+class RevocationStore(Protocol):
+    """Verifier-side lookup: is a kid revoked at a given HLC?
+
+    Production deployments ship a libp2p-gossiped store backed by the
+    transparency log; sandboxes use the in-memory ``InMemoryRevocationStore``.
+    """
+
+    def is_revoked(self, kid: bytes, hlc: tuple[int, int]) -> RevocationEntry | None:
+        """Return the matching RevocationEntry if `kid` is revoked at or
+        before `hlc`, else None. Statements with HLC strictly less than
+        the entry's `revoked_at_hlc` MUST return None (historical-claim
+        immutability)."""
+        ...
+
+
+@dataclass
+class InMemoryRevocationStore:
+    """Sandbox/test store. Holds a single RevocationList per namespace."""
+
+    crl: RevocationList | None = None
+
+    def install(self, crl: RevocationList) -> None:
+        """Replace the current CRL. Verifies the signature first.
+
+        For composite namespace-root keys the caller must validate the
+        signature themselves before install (the in-memory store doesn't
+        know which alg the issuer uses); for Ed25519 we self-check.
+        """
+        if not crl.verify():
+            raise ValueError(
+                "RevocationList signature does not verify under issued_by; "
+                "refusing to install (rule_id=HM-KEY-REVOKED-001)"
+            )
+        self.crl = crl
+
+    def is_revoked(self, kid: bytes, hlc: tuple[int, int]) -> RevocationEntry | None:
+        if self.crl is None:
+            return None
+        for e in self.crl.entries:
+            if bytes(e.kid) != bytes(kid):
+                continue
+            # Statements signed strictly before revocation remain valid.
+            if hlc >= e.revoked_at_hlc:
+                return e
+        return None
+
+
+__all__ = [
+    "InMemoryRevocationStore",
+    "RevocationEntry",
+    "RevocationList",
+    "RevocationReason",
+    "RevocationStore",
+]

hypermind/rule_ids.py

@@ -0,0 +1,135 @@
+"""Rule-ID taxonomy — stable across minor versions.
+
+Each constant maps ``rule_id`` → ``spec_ref``. Use these via
+``BlockReason(rule_id=RULE_..., spec_ref=SPEC_REFS[RULE_...], ...)``.
+
+Renaming or removing a constant is a MAJOR-version bump per the public-surface
+stability contract. Adding new rule_ids is MINOR.
+
+The 15 v0.1 rule_ids come from the cycle-2026-04-27 expert panel
+synthesis. The v0.8 expansion (ROADMAP §0.8.15) adds ~18 more covering
+namespace bootstrap, capability lifetime, wire/record discriminators,
+vouching, consult/oracle/dispute/witness lifecycle, partition,
+inclusion-proof verification, FROST quorum, and CRL freshness.
+"""
+
+from __future__ import annotations
+
+# v0.1 rule_ids — DO NOT renumber; suffix `-001` reserves room for revisions.
+ADMIT_RAMP = "HM-ADMIT-RAMP-001"
+BOND_TOPIC_MISMATCH = "HM-BOND-MISMATCH-001"
+CAP_SCOPE = "HM-CAP-SCOPE-001"
+CAP_CHAIN = "HM-CAP-CHAIN-001"
+WITNESS_LAG = "HM-WIT-LAG-001"
+HLC_SKEW = "HM-HLC-SKEW-001"
+ALG_PIN = "HM-ALG-PIN-001"
+WIRE_REENCODE = "HM-WIRE-REENCODE-001"
+PQ_REQUIRED = "HM-PQ-REQUIRED-001"
+FROST_REPLAY = "HM-FROST-REPLAY-001"
+RATE_CAP = "HM-RATE-CAP-001"
+DISPUTE_FSM = "HM-DISPUTE-FSM-001"
+KEY_REVOKED = "HM-KEY-REVOKED-001"
+MIN_ALG = "HM-MIN-ALG-001"
+PROTO_VER = "HM-PROTO-VER-001"
+
+# v0.8 rule_ids (ROADMAP §0.8.15) — taxonomy completion.
+NAMESPACE_BOOTSTRAP = "HM-NAMESPACE-BOOTSTRAP-001"
+CAP_EXPIRED = "HM-CAP-EXPIRED-001"
+CAP_FUTURE_DATED = "HM-CAP-FUTURE-DATED-001"
+WIRE_VERSION = "HM-WIRE-VERSION-001"
+RECORD_TYPE = "HM-RECORD-TYPE-001"
+NAMESPACE_MISMATCH = "HM-NAMESPACE-MISMATCH-001"
+VOUCH_CAP = "HM-VOUCH-CAP-001"
+VOUCH_SELF = "HM-VOUCH-SELF-001"
+CONSULT_NO_PANEL = "HM-CONSULT-NO-PANEL-001"
+CONSULT_DEADLOCK = "HM-CONSULT-DEADLOCK-001"
+ORACLE_AUTH = "HM-ORACLE-AUTH-001"
+DISPUTE_DOUBLE = "HM-DISPUTE-DOUBLE-001"
+DISPUTE_QUORUM = "HM-DISPUTE-QUORUM-001"
+WITNESS_OFFLINE = "HM-WITNESS-OFFLINE-001"
+PARTITION_DETECTED = "HM-PARTITION-DETECTED-001"
+MERKLE_INCLUSION = "HM-MERKLE-INCLUSION-001"
+FROST_THRESHOLD = "HM-FROST-THRESHOLD-001"
+CRL_SIGNATURE = "HM-CRL-SIGNATURE-001"
+CRL_STALE = "HM-CRL-STALE-001"
+
+
+SPEC_REFS: dict[str, str] = {
+    # v0.1
+    ADMIT_RAMP: "draft-hypermind-scitt-contested-claims §7.2",
+    BOND_TOPIC_MISMATCH: "draft-hypermind-scitt-contested-claims §10.4",
+    CAP_SCOPE: "draft-hypermind-scitt-contested-claims §11.3",
+    CAP_CHAIN: "draft-hypermind-scitt-contested-claims §11.4",
+    WITNESS_LAG: "draft-hypermind-scitt-contested-claims §6.5",
+    HLC_SKEW: "draft-hypermind-scitt-contested-claims §5.2",
+    ALG_PIN: "draft-hypermind-scitt-contested-claims §3.1",
+    WIRE_REENCODE: "draft-hypermind-scitt-contested-claims §3.4",
+    PQ_REQUIRED: "draft-hypermind-scitt-contested-claims §3.6",
+    FROST_REPLAY: "draft-hypermind-scitt-contested-claims §9.3",
+    RATE_CAP: "draft-hypermind-scitt-contested-claims §12.2",
+    DISPUTE_FSM: "draft-hypermind-scitt-contested-claims §10.2",
+    KEY_REVOKED: "draft-hypermind-scitt-contested-claims §12.1 (Revocation)",
+    MIN_ALG: "draft-hypermind-scitt-contested-claims §3.7 (min_signature_alg)",
+    PROTO_VER: "draft-hypermind-scitt-contested-claims §17 (protocol-version-negotiation)",
+    # v0.8
+    NAMESPACE_BOOTSTRAP: "draft-hypermind-scitt-contested-claims §8.1 (admission)",
+    CAP_EXPIRED: "draft-hypermind-scitt-contested-claims §11.5 (capability lifetime)",
+    CAP_FUTURE_DATED: "draft-hypermind-scitt-contested-claims §11.5 (capability lifetime)",
+    WIRE_VERSION: "draft-hypermind-scitt-contested-claims §3.3 (wire_version)",
+    RECORD_TYPE: "draft-hypermind-scitt-contested-claims §3.5 (record_type)",
+    NAMESPACE_MISMATCH: "draft-hypermind-scitt-contested-claims §8.2 (namespace binding)",
+    VOUCH_CAP: "draft-hypermind-scitt-contested-claims §7.4 (vouch contribution cap)",
+    VOUCH_SELF: "draft-hypermind-scitt-contested-claims §7.4 (no self-vouching)",
+    CONSULT_NO_PANEL: "draft-hypermind-scitt-contested-claims §5.1 (panel selection)",
+    CONSULT_DEADLOCK: "draft-hypermind-scitt-contested-claims §5.6 (consult timeout)",
+    ORACLE_AUTH: "draft-hypermind-scitt-contested-claims §6.7 (oracle authority)",
+    DISPUTE_DOUBLE: "draft-hypermind-scitt-contested-claims §10.5 (double-dispute)",
+    DISPUTE_QUORUM: "draft-hypermind-scitt-contested-claims §10.6 (close quorum)",
+    WITNESS_OFFLINE: "draft-hypermind-scitt-contested-claims §6.5 (witness availability)",
+    PARTITION_DETECTED: "draft-hypermind-scitt-contested-claims §10.7 (UNRESOLVED_PARTITION)",
+    MERKLE_INCLUSION: "draft-hypermind-scitt-contested-claims §6.4 (inclusion proof)",
+    FROST_THRESHOLD: "draft-hypermind-scitt-contested-claims §9.2 (k-of-n)",
+    CRL_SIGNATURE: "draft-hypermind-scitt-contested-claims §12.3 (CRL signature)",
+    CRL_STALE: "draft-hypermind-scitt-contested-claims §12.4 (CRL freshness)",
+}
+
+
+__all__ = [
+    # v0.1
+    "ADMIT_RAMP",
+    "ALG_PIN",
+    "BOND_TOPIC_MISMATCH",
+    "CAP_CHAIN",
+    # v0.8
+    "CAP_EXPIRED",
+    "CAP_FUTURE_DATED",
+    "CAP_SCOPE",
+    "CONSULT_DEADLOCK",
+    "CONSULT_NO_PANEL",
+    "CRL_SIGNATURE",
+    "CRL_STALE",
+    "DISPUTE_DOUBLE",
+    "DISPUTE_FSM",
+    "DISPUTE_QUORUM",
+    "FROST_REPLAY",
+    "FROST_THRESHOLD",
+    "HLC_SKEW",
+    "KEY_REVOKED",
+    "MERKLE_INCLUSION",
+    "MIN_ALG",
+    "NAMESPACE_BOOTSTRAP",
+    "NAMESPACE_MISMATCH",
+    "ORACLE_AUTH",
+    "PARTITION_DETECTED",
+    "PQ_REQUIRED",
+    "PROTO_VER",
+    "RATE_CAP",
+    "RECORD_TYPE",
+    "SPEC_REFS",
+    "VOUCH_CAP",
+    "VOUCH_SELF",
+    "WIRE_REENCODE",
+    "WIRE_VERSION",
+    "WITNESS_LAG",
+    "WITNESS_OFFLINE",
+]

hypermind/schemas/encrypted_statement.cddl

@@ -0,0 +1,28 @@
+; encrypted_statement.cddl - EncryptedStatement payload schema
+; HyperMind v0.9.x - wire_version >= 2
+; This file is co-located in src/hypermind/schemas/ and reference_verifier/schemas/.
+; Keep them byte-equal.
+;
+; Encoding: RFC 8949 deterministic CBOR (sec 4.2). This payload is the
+; ciphertext envelope used for private/hybrid namespace records. The outer
+; SignedStatement carries this CBOR array as its payload bstr; the inner
+; plaintext (after AEAD decryption) is itself a deterministic-CBOR record.
+;
+; HPKE alignment: kdf and aead values use the IANA HPKE registry from
+; RFC 9180 sec 7 (e.g. kdf=1 HKDF-SHA256, aead=1 AES-128-GCM, aead=2
+; AES-256-GCM, aead=3 ChaCha20-Poly1305). Recipient.enc carries the HPKE
+; encapsulated key for that recipient.
+
+EncryptedStatement = [
+  kdf:             int,                       ; HPKE KDF id (RFC 9180 sec 7.2)
+  aead:            int,                       ; HPKE AEAD id (RFC 9180 sec 7.3)
+  enc_recipients:  [+ Recipient],
+  aad_hash:        bstr .size 32,             ; BLAKE3-256 of the AEAD additional-authenticated-data
+  ciphertext:      bstr,                      ; AEAD output for the chosen suite
+  ? epoch_tag:     bstr .size 16              ; optional MLS-style epoch / key-rotation tag
+]
+
+Recipient = {
+  recipient_kid:   bstr .size 32,             ; Ed25519 pubkey half of the recipient
+  enc:             bstr                       ; HPKE encapsulated key (suite-dependent length)
+}

hypermind/schemas/namespace_accept.cddl

@@ -0,0 +1,20 @@
+; namespace_accept.cddl - NAMESPACE_ACCEPT record payload schema
+; HyperMind v0.9.x - wire_version >= 2
+; This file is co-located in src/hypermind/schemas/ and reference_verifier/schemas/.
+; Keep them byte-equal.
+;
+; Encoding: RFC 8949 deterministic CBOR (sec 4.2). This payload is carried
+; as the COSE_Sign1 payload bstr for record_type = "NAMESPACE_ACCEPT".
+; Its BLAKE3-256 digest is bound into the protected header under the
+; HM_ENVELOPE_SCHEMA_HASH (-65605) label.
+
+NamespaceAccept = {
+  ns_id:            bstr .size 16,
+  invitee_kid:      bstr .size 32,            ; MUST equal kid of the signer
+  invite_hash:      bstr .size 32,            ; BLAKE3-256 of the canonical NamespaceInvite payload
+  accepted_at_hlc:  hlc,
+  signature:        bstr                      ; Ed25519 (or hybrid) signature by invitee_kid
+}
+
+; Hybrid Logical Clock - [logical_ms, counter, node_id]
+hlc = [uint, uint, bstr]

hypermind/schemas/namespace_create.cddl

@@ -0,0 +1,25 @@
+; namespace_create.cddl - NAMESPACE_CREATE record payload schema
+; HyperMind v0.9.x - wire_version >= 2
+; This file is co-located in src/hypermind/schemas/ and reference_verifier/schemas/.
+; Keep them byte-equal.
+;
+; Encoding: RFC 8949 deterministic CBOR (sec 4.2). This payload is carried
+; as the COSE_Sign1 payload bstr for record_type = "NAMESPACE_CREATE".
+; Its BLAKE3-256 digest is bound into the protected header under the
+; HM_ENVELOPE_SCHEMA_HASH (-65605) label.
+
+NamespaceCreate = {
+  ns_id:               bstr .size 16,         ; UUIDv7-shaped namespace id
+  founding_cohort:     [+ bstr .size 32],     ; list of founder kids (Ed25519 pubkey halves)
+  threshold:           { k: uint, n: uint },  ; FROST k-of-n threshold parameters
+  dkg_transcript_hash: bstr .size 32,         ; BLAKE3-256 of the DKG transcript
+  root_pubkey:         bstr,                  ; FROST group public key (aggregated)
+  visibility:          ("public" / "private" / "hybrid"),
+  created_at_hlc:      hlc,
+  frost_signature:     bstr                   ; RFC 9591 FROST signature over the canonical preimage
+}
+
+; Hybrid Logical Clock - [logical_ms, counter, node_id]
+; Mirrors the definition in wire-v0.1.cddl; duplicated here so this
+; payload schema stands alone for digest computation.
+hlc = [uint, uint, bstr]

hypermind/schemas/namespace_founding_attest.cddl

@@ -0,0 +1,30 @@
+; namespace_founding_attest.cddl - NAMESPACE_FOUNDING_ATTEST record payload schema
+; HyperMind v0.9.x - wire_version >= 2
+; This file is co-located in src/hypermind/schemas/ and reference_verifier/schemas/.
+; Keep them byte-equal.
+;
+; Encoding: RFC 8949 deterministic CBOR (sec 4.2). This payload is carried
+; as the COSE_Sign1 payload bstr for record_type = "NAMESPACE_FOUNDING_ATTEST".
+; Its BLAKE3-256 digest is bound into the protected header under the
+; HM_ENVELOPE_SCHEMA_HASH (-65605) label.
+
+NamespaceFoundingAttest = {
+  ns_id:               bstr .size 16,
+  members:             [+ Member],
+  dkg_transcript_hash: bstr .size 32,
+  root_pubkey:         bstr,                  ; FROST group public key
+  ? root_cert:         bstr,                  ; optional X.509 / SCITT root cert chain
+  visibility:          ("public" / "private" / "hybrid"),
+  created_at_hlc:      hlc,
+  frost_signature:     bstr                   ; RFC 9591 FROST signature
+}
+
+Member = {
+  kid:                 bstr .size 32,         ; Ed25519 pubkey half = stable address
+  jurisdiction:        tstr,                  ; ISO 3166-1 alpha-2 or "XX" for unspecified
+  org_did:             tstr,                  ; W3C DID for the founding org
+  coi_disclosure_hash: bstr .size 32          ; BLAKE3-256 of conflict-of-interest disclosure
+}
+
+; Hybrid Logical Clock - [logical_ms, counter, node_id]
+hlc = [uint, uint, bstr]

hypermind/schemas/namespace_invite.cddl

@@ -0,0 +1,22 @@
+; namespace_invite.cddl - NAMESPACE_INVITE record payload schema
+; HyperMind v0.9.x - wire_version >= 2
+; This file is co-located in src/hypermind/schemas/ and reference_verifier/schemas/.
+; Keep them byte-equal.
+;
+; Encoding: RFC 8949 deterministic CBOR (sec 4.2). This payload is carried
+; as the COSE_Sign1 payload bstr for record_type = "NAMESPACE_INVITE".
+; Its BLAKE3-256 digest is bound into the protected header under the
+; HM_ENVELOPE_SCHEMA_HASH (-65605) label.
+
+NamespaceInvite = {
+  ns_id:           bstr .size 16,
+  inviter_kid:     bstr .size 32,             ; member already in the namespace
+  invitee_kid:     bstr .size 32,             ; prospective member
+  scope:           { rooms: [* tstr], topics: [* tstr] },
+  valid_from_hlc:  hlc,
+  valid_until_hlc: hlc,
+  signature:       bstr                       ; Ed25519 (or hybrid) signature by inviter_kid
+}
+
+; Hybrid Logical Clock - [logical_ms, counter, node_id]
+hlc = [uint, uint, bstr]

hypermind/schemas/wire-v0.1.cddl

@@ -0,0 +1,73 @@
+; HyperMind SCITT Contested-Claims Profile — wire format v0.1
+; draft-hypermind-scitt-contested-claims-profile-00
+;
+; This CDDL is the canonical schema for the SignedStatement envelope.
+; Its BLAKE3-256 digest is bound into every protected header under the
+; HM_ENVELOPE_SCHEMA_HASH (-65605) label. Any change to this file is a
+; wire-format change and MUST bump WIRE_VERSION.
+;
+; Encoding: RFC 8949 deterministic CBOR (§4.2). Outer envelope is a
+; COSE_Sign1 4-tuple per RFC 9052 §4.2.
+
+SignedStatement = [
+  protected:   bstr .cbor protected-header,
+  unprotected: { * (int / tstr) => any },
+  payload:     bstr,
+  signature:   bstr
+]
+
+; ---- Protected header --------------------------------------------------
+; Standard COSE labels:
+;   1  alg
+;   4  kid (32-byte Ed25519 public key half = stable agent address)
+;
+; HyperMind extension labels (proposed IANA -65600..-65624):
+
+protected-header = {
+  1                => sig-alg,         ; COSE alg
+  4                => bstr .size 32,   ; issuer_kid
+  -65601           => record-type,
+  -65602           => bstr .size 16,   ; namespace_id (UUIDv7-shaped)
+  -65603           => hlc,
+  -65604           => sig-alg,         ; sig_alg_disc — MUST equal label 1
+  -65605           => bstr .size 32,   ; envelope_schema_hash (BLAKE3 of this CDDL)
+  -65606           => uint,            ; wire_version (= 0 for v0.1)
+  -65607           => bool,            ; pq_required
+  -65611           => uint,            ; protocol_version (HyperMind v0.5+; = 0)
+  ? -65608         => uncertainty,     ; receipt_uncertainty (RECEIPT only)
+  ? -65609         => [+ bstr .size 32], ; confirmer_set (SEAL only, ≥3)
+  ? -65610         => dispute-state,
+  ? -65620         => bstr .size 32,   ; dispute_target_kid (DISPUTE only)
+  ? -65621         => dispute-subtype,
+  ? -65622         => bond-commitment,
+  ? -65623         => [* bstr .size 32], ; prior_dispute_chain
+  ? -65624         => ramp-state
+}
+
+record-type      = "SEAL" / "RECEIPT" / "DISPUTE" / "KEY_ROTATE"
+                 / "NAMESPACE_FOUNDING_ATTEST"
+
+dispute-state    = "OPEN" / "ARGUE" / "COUNTER" / "FRIVOLOUS"
+                 / "CLOSED" / "UNRESOLVED_PARTITION"
+dispute-subtype  = "OPEN" / "ARGUE" / "COUNTER" / "FRIVOLOUS"
+
+; v0.1 algorithms (RFC 9053 + composite per LAMPS draft):
+;   -8  Ed25519
+;  -49  Ed25519+ML-DSA-65 composite
+sig-alg          = -8 / -49
+
+; Hybrid Logical Clock — [logical_ms, counter, node_id]
+hlc              = [uint, uint, bstr]
+
+; Receipt uncertainty bundle — opaque CBOR map; semantics in §03-messages.md
+uncertainty      = { * (int / tstr) => any }
+
+; Bond commitment — opaque CBOR map; semantics in §10-disputes.md
+bond-commitment  = { * (int / tstr) => any }
+
+; Ramp state — opaque CBOR map; semantics in §10-disputes.md
+ramp-state       = { * (int / tstr) => any }
+
+; ---- Sig_structure preimage (RFC 9052 §4.4) ---------------------------
+; The signed bytes are deterministic-CBOR(Sig_structure) where:
+;   Sig_structure = [ "Signature1", protected, h'' (ext_aad), payload ]

hypermind/simlab/__init__.py

@@ -0,0 +1,15 @@
+"""HyperMind SimLab — multi-sim app: registry, runner, scenarios.
+
+Public API:
+    SimConfig            — declarative simulation request shape
+    run_persona_sim()    — async entrypoint that runs a persona-panel sim
+    SimResult            — what run_persona_sim() returns
+
+The HTTP surface lives in `src/hypermind/api/app.py` (`/v1/sims/*`); the
+CLI surface is `hmctl simlab`.
+"""
+
+from .config import SimConfig
+from .scenario import SimResult, run_persona_sim
+
+__all__ = ["SimConfig", "SimResult", "run_persona_sim"]