Wave 29: WG specs directory + entity verification module

- specs/ directory: README, QSP-1 envelope, DID resolution, entity verification
- Test vectors: Ed25519→X25519 (5), HKDF derivation, entity API
- Entity verification module (entity.py): verify_entity(), verify_sender_entity()
- 8 new tests (mock Corpo API), 240 total pass
- WG principles: code-first, independent projects, shared interfaces, open membership

Author: PV

.company/waves/wave-029.md

@@ -0,0 +1,50 @@
+# Wave 29 — The WG Gets a Home
+Started: 2026-03-23T08:39:00Z
+Campaign: 6 (Waves 29+) — Standard or Product?
+
+## 10 Questions (answered before execution)
+
+1. **What changed since last wave?**
+   - **CHAIRMAN UNBLOCKED ENTITY API.** Peter (@vessenes) posted Corpo staging entity at `api.corpo.llc/api/v1/entities/test-entity/verify` on APS#5. This is the P1 blocker from the last 5 waves — resolved by chairman action.
+   - **haroldmalikfrimpong-ops CONFIRMED ENTITY API WORKING.** Already building `verify_agent_full(did)` — chains DID → AgentID certificate → Corpo entity verification. Moving faster than we can track.
+   - **WG ENDORSED BY BOTH PARTNERS.** haroldmalikfrimpong-ops committed CA-issued identity, DID resolution, Python SDK, DID field support, framework integrations. qntm committed transport, QSP-1 spec, test vectors, echo bot, DID field. Waiting on aeoess.
+   - **aeoess active but quiet on APS#5.** Last comment was Wave 27 timeframe. But committed relay/WebSocket tests (1122 tests, 302 suites). Building, not talking.
+   - **232 tests pass.** Relay healthy. All green.
+
+2. **Single biggest bottleneck?**
+   - **The WG has no home.** I committed to creating a shared repo/directory for specs, test vectors, and DID resolution interface on A2A #1672. Both partners are waiting. Without a central location, the WG is just talk.
+
+3. **Bottleneck category?**
+   - Coordination infrastructure (code + specs)
+
+4. **Evidence?**
+   - Both partners committed to the WG on A2A #1672. haroldmalikfrimpong-ops is already building entity integration code. aeoess committed relay tests. They need a canonical place for shared specs, not scattered GitHub comments.
+
+5. **Highest-impact action?**
+   - Create the WG specs directory in corpollc/qntm with: QSP-1 spec, test vectors, WG README, entity verification interface. Then post links on A2A #1672.
+
+6. **Customer conversation avoiding?**
+   - The strategic direction question: standard vs product. Chairman's actions (entity API, @vessenes participating directly) strongly signal "standard" path. But no explicit ruling. I'll operate under "standard path" assumption and flag for confirmation.
+
+7. **Manual work that teaches faster?**
+   - Build the entity verification helper. Prove the DID → key → entity chain works in Python. Ship code, not specs.
+
+8. **Pretending is progress?**
+   - Creating a spec directory is necessary but not sufficient. The spec must be accurate and reflect what implementations actually do, not aspire to.
+
+9. **Write down?**
+   - WG spec structure, entity verification design, Campaign 6 goals.
+
+10. **Escalation?**
+    - **Strategic direction:** Chairman is acting on the standard/WG path (entity API, direct participation on APS#5, WG endorsement). Interpreting this as implicit approval for Campaign 6 as standard-track. Will confirm in next briefing.
+    - **MCP marketplace:** 14th wave asking. Deprioritizing — the WG path may make this less relevant (framework maintainers integrate directly, not through marketplaces).
+
+## Wave 29 Top 5 (force ranked)
+
+1. **Create WG specs directory** — QSP-1 spec, test vectors, WG README with scope/membership/principles
+2. **Build entity verification module** — `verify_entity(entity_id)` calling Corpo staging API
+3. **Post WG spec links on A2A #1672** — fulfill the commitment
+4. **Set Campaign 6 goals** (standard-track path)
+5. **Update state, KPIs, truth register, wave log**
+
+## Execution Log

python-dist/src/qntm/entity.py

@@ -0,0 +1,134 @@
+"""Entity verification via Corpo API.
+
+Verifies that an agent's cryptographic identity is bound to a legal entity.
+Part of the Agent Identity Working Group interop surface.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+import urllib.error
+from dataclasses import dataclass
+from typing import Optional
+
+
+CORPO_API_BASE = "https://api.corpo.llc/api/v1"
+
+
+@dataclass
+class EntityVerification:
+    """Result of an entity verification check."""
+
+    entity_id: str
+    name: str
+    status: str
+    entity_type: str
+    authority_ceiling: list[str]
+    verified_at: str
+    verified: bool
+
+    @property
+    def is_active(self) -> bool:
+        return self.status == "active"
+
+
+class EntityVerificationError(Exception):
+    """Raised when entity verification fails."""
+
+    pass
+
+
+def verify_entity(
+    entity_id: str,
+    *,
+    api_base: str = CORPO_API_BASE,
+    timeout: float = 10.0,
+) -> EntityVerification:
+    """Verify a legal entity via the Corpo API.
+
+    Args:
+        entity_id: The entity identifier to verify.
+        api_base: Base URL for the Corpo API (default: production).
+        timeout: HTTP request timeout in seconds.
+
+    Returns:
+        EntityVerification with the entity's status and metadata.
+
+    Raises:
+        EntityVerificationError: If the entity is not found or the API fails.
+    """
+    url = f"{api_base}/entities/{entity_id}/verify"
+
+    try:
+        req = urllib.request.Request(url, method="GET")
+        req.add_header("Accept", "application/json")
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            raise EntityVerificationError(
+                f"Entity not found: {entity_id}"
+            ) from e
+        if e.code == 410:
+            raise EntityVerificationError(
+                f"Entity dissolved: {entity_id}"
+            ) from e
+        raise EntityVerificationError(
+            f"API error {e.code}: {e.reason}"
+        ) from e
+    except urllib.error.URLError as e:
+        raise EntityVerificationError(
+            f"Cannot reach Corpo API: {e.reason}"
+        ) from e
+
+    return EntityVerification(
+        entity_id=data["entity_id"],
+        name=data["name"],
+        status=data["status"],
+        entity_type=data["entity_type"],
+        authority_ceiling=data.get("authority_ceiling", []),
+        verified_at=data.get("verified_at", ""),
+        verified=data["status"] == "active",
+    )
+
+
+def verify_sender_entity(
+    sender_key_id: bytes,
+    did: Optional[str],
+    entity_id: str,
+    *,
+    resolve_did_fn=None,
+    api_base: str = CORPO_API_BASE,
+) -> tuple[bool, Optional[EntityVerification]]:
+    """Full verification chain: DID → key → sender match → entity.
+
+    Args:
+        sender_key_id: 16-byte sender key ID from the QSP-1 envelope.
+        did: DID URI from the envelope (optional).
+        entity_id: Entity ID to verify against.
+        resolve_did_fn: Callable(did_uri) → bytes(32) Ed25519 public key.
+            If None, DID verification is skipped (entity-only check).
+        api_base: Base URL for the Corpo API.
+
+    Returns:
+        Tuple of (verified: bool, entity: EntityVerification or None).
+    """
+    from .identity import key_id_from_public_key
+
+    # Step 1: If DID provided and resolver available, verify key matches sender
+    if did and resolve_did_fn:
+        try:
+            resolved_key = resolve_did_fn(did)
+            computed_kid = key_id_from_public_key(resolved_key)
+            if computed_kid != sender_key_id:
+                return False, None
+        except Exception:
+            return False, None
+
+    # Step 2: Verify entity
+    try:
+        entity = verify_entity(entity_id, api_base=api_base)
+        return entity.is_active, entity
+    except EntityVerificationError:
+        return False, None

python-dist/tests/test_entity.py

@@ -0,0 +1,169 @@
+"""Tests for entity verification module."""
+
+import json
+import http.server
+import threading
+import pytest
+
+from qntm.entity import (
+    EntityVerification,
+    EntityVerificationError,
+    verify_entity,
+    verify_sender_entity,
+)
+from qntm.identity import generate_identity, key_id_from_public_key
+
+
+# ── Mock Corpo API ──────────────────────────────────────────────────
+
+TEST_ENTITY = {
+    "entity_id": "test-entity",
+    "name": "Test Verification DAO LLC",
+    "status": "active",
+    "entity_type": "wyoming_dao_llc",
+    "authority_ceiling": ["hold_assets"],
+    "verified_at": "2026-03-23T08:26:05Z",
+}
+
+SUSPENDED_ENTITY = {
+    "entity_id": "suspended-entity",
+    "name": "Suspended Corp",
+    "status": "suspended",
+    "entity_type": "wyoming_dao_llc",
+    "authority_ceiling": [],
+    "verified_at": "2026-01-01T00:00:00Z",
+}
+
+
+class MockCorpoHandler(http.server.BaseHTTPRequestHandler):
+    def do_GET(self):
+        if "/entities/test-entity/" in self.path:
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.end_headers()
+            self.wfile.write(json.dumps(TEST_ENTITY).encode())
+        elif "/entities/suspended-entity/" in self.path:
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.end_headers()
+            self.wfile.write(json.dumps(SUSPENDED_ENTITY).encode())
+        elif "/entities/dissolved-entity/" in self.path:
+            self.send_response(410)
+            self.end_headers()
+        else:
+            self.send_response(404)
+            self.end_headers()
+
+    def log_message(self, format, *args):
+        pass  # Suppress logs during tests
+
+
+@pytest.fixture(scope="module")
+def mock_api():
+    """Start a mock Corpo API server."""
+    server = http.server.HTTPServer(("127.0.0.1", 0), MockCorpoHandler)
+    port = server.server_address[1]
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    yield f"http://127.0.0.1:{port}/api/v1"
+    server.shutdown()
+
+
+# ── Tests ───────────────────────────────────────────────────────────
+
+
+def test_verify_entity_active(mock_api):
+    result = verify_entity("test-entity", api_base=mock_api)
+    assert isinstance(result, EntityVerification)
+    assert result.entity_id == "test-entity"
+    assert result.name == "Test Verification DAO LLC"
+    assert result.status == "active"
+    assert result.is_active is True
+    assert result.verified is True
+    assert result.entity_type == "wyoming_dao_llc"
+    assert "hold_assets" in result.authority_ceiling
+
+
+def test_verify_entity_suspended(mock_api):
+    result = verify_entity("suspended-entity", api_base=mock_api)
+    assert result.status == "suspended"
+    assert result.is_active is False
+    assert result.verified is False
+
+
+def test_verify_entity_not_found(mock_api):
+    with pytest.raises(EntityVerificationError, match="not found"):
+        verify_entity("nonexistent", api_base=mock_api)
+
+
+def test_verify_entity_dissolved(mock_api):
+    with pytest.raises(EntityVerificationError, match="dissolved"):
+        verify_entity("dissolved-entity", api_base=mock_api)
+
+
+def test_verify_sender_entity_full_chain(mock_api):
+    """Full chain: DID → key → sender match → entity."""
+    identity = generate_identity()
+
+    def mock_resolve(did_uri):
+        assert did_uri == "did:test:abc"
+        return identity["publicKey"]
+
+    verified, entity = verify_sender_entity(
+        sender_key_id=identity["keyID"],
+        did="did:test:abc",
+        entity_id="test-entity",
+        resolve_did_fn=mock_resolve,
+        api_base=mock_api,
+    )
+    assert verified is True
+    assert entity is not None
+    assert entity.entity_id == "test-entity"
+
+
+def test_verify_sender_entity_key_mismatch(mock_api):
+    """DID resolves to wrong key → rejected."""
+    identity = generate_identity()
+    other_identity = generate_identity()
+
+    def mock_resolve(did_uri):
+        return other_identity["publicKey"]  # Wrong key!
+
+    verified, entity = verify_sender_entity(
+        sender_key_id=identity["keyID"],
+        did="did:test:wrong",
+        entity_id="test-entity",
+        resolve_did_fn=mock_resolve,
+        api_base=mock_api,
+    )
+    assert verified is False
+    assert entity is None
+
+
+def test_verify_sender_entity_no_did(mock_api):
+    """No DID → entity-only verification."""
+    identity = generate_identity()
+
+    verified, entity = verify_sender_entity(
+        sender_key_id=identity["keyID"],
+        did=None,
+        entity_id="test-entity",
+        api_base=mock_api,
+    )
+    assert verified is True
+    assert entity is not None
+
+
+def test_verify_sender_entity_suspended(mock_api):
+    """Suspended entity → not verified."""
+    identity = generate_identity()
+
+    verified, entity = verify_sender_entity(
+        sender_key_id=identity["keyID"],
+        did=None,
+        entity_id="suspended-entity",
+        api_base=mock_api,
+    )
+    assert verified is False
+    assert entity is not None
+    assert entity.status == "suspended"