apsimo 1.3.0__py3-none-any.whl

apsimo/contacts/migrations/001_contacts_schema.sql

@@ -0,0 +1,141 @@
+-- colony/contacts/migrations/001_contacts_schema.sql
+
+-- ─── Contacts ────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS contacts (
+  contact_id          TEXT PRIMARY KEY,         -- cid-<timestamp_ms>-<random7>
+  display_name        TEXT,
+  given_name          TEXT,
+  family_name         TEXT,
+  organization        TEXT,
+  relationship_score  REAL NOT NULL DEFAULT 0.0
+                        CHECK(relationship_score >= 0.0 AND relationship_score <= 1.0),
+  trust_tier          TEXT NOT NULL DEFAULT 'unknown'
+                        CHECK(trust_tier IN ('inner_circle','trusted','regular',
+                                             'peripheral','silenced','acquaintance','unknown')),
+  interaction_allowed INTEGER NOT NULL DEFAULT 1
+                        CHECK(interaction_allowed IN (0,1)),
+  tags_json           TEXT NOT NULL DEFAULT '[]',  -- JSON array of strings
+  privacy_level       TEXT NOT NULL DEFAULT 'private'
+                        CHECK(privacy_level IN ('public','private','restricted')),
+  person_node_id      TEXT,
+  notes               TEXT,
+  import_source       TEXT NOT NULL DEFAULT 'manual',
+  first_seen_at       TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+  last_interaction_at TEXT,
+  interaction_count   INTEGER NOT NULL DEFAULT 0,
+  enrichment_source   TEXT NOT NULL DEFAULT '[]',  -- JSON array
+  enrichment_last_at  TEXT,
+  deleted_at          TEXT,                        -- NULL until soft-deleted
+  created_at          TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+  updated_at          TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+  timezone            TEXT                          -- IANA tz for this contact (v0.21.0), editable
+);
+
+CREATE INDEX IF NOT EXISTS idx_contacts_tier
+  ON contacts(trust_tier) WHERE deleted_at IS NULL;
+
+CREATE INDEX IF NOT EXISTS idx_contacts_person_node
+  ON contacts(person_node_id) WHERE person_node_id IS NOT NULL;
+
+-- ─── Contact Handles ─────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS contact_handles (
+  handle_id    TEXT PRIMARY KEY,               -- hdl-<timestamp_ms>-<random7>
+  contact_id   TEXT NOT NULL REFERENCES contacts(contact_id) ON DELETE CASCADE,
+  -- Keep in sync with the delivery channel set (delivery/channels.py):
+  -- whatsapp/discord/slack were deliverable but unstorable before v0.17.
+  gateway      TEXT NOT NULL
+                 CHECK(gateway IN ('imessage','telegram','whatsapp','discord',
+                                   'slack','email','sms','signal','custom')),
+  address      TEXT NOT NULL,
+  is_primary   INTEGER NOT NULL DEFAULT 0
+                 CHECK(is_primary IN (0,1)),
+  verified     INTEGER NOT NULL DEFAULT 0
+                 CHECK(verified IN (0,1)),
+  confidence   REAL NOT NULL DEFAULT 1.0
+                 CHECK(confidence >= 0.0 AND confidence <= 1.0),
+  source       TEXT NOT NULL DEFAULT 'manual',
+  created_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+  UNIQUE(gateway, address)
+);
+
+CREATE INDEX IF NOT EXISTS idx_handles_contact
+  ON contact_handles(contact_id);
+
+CREATE INDEX IF NOT EXISTS idx_handles_gateway_address
+  ON contact_handles(gateway, address);
+
+-- ─── Contact Audit ────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS contact_audit (
+  id           TEXT PRIMARY KEY,               -- cau-<timestamp_ms>-<random7>
+  contact_id   TEXT NOT NULL,
+  action       TEXT NOT NULL,
+    -- created, handle_added, tier_changed, interaction_toggled,
+    -- enriched, soft_deleted, hard_deleted, blocked, unblocked
+  detail       TEXT,                           -- JSON object with action-specific fields
+  performed_by TEXT NOT NULL DEFAULT 'system', -- 'operator', 'system', 'auto'
+  created_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_contact_audit_contact
+  ON contact_audit(contact_id, created_at DESC);
+
+-- ─── Merge Proposals ─────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS contact_merge_proposals (
+  id              TEXT PRIMARY KEY,            -- cmp-<timestamp_ms>-<random7>
+  contact_id_a    TEXT NOT NULL REFERENCES contacts(contact_id),
+  contact_id_b    TEXT NOT NULL REFERENCES contacts(contact_id),
+  confidence      REAL NOT NULL,
+  reason          TEXT NOT NULL,
+  status          TEXT NOT NULL DEFAULT 'pending'
+                    CHECK(status IN ('pending','approved','rejected','auto_merged')),
+  proposed_at     TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+  resolved_at     TEXT,
+  UNIQUE(contact_id_a, contact_id_b)
+);
+
+CREATE INDEX IF NOT EXISTS idx_merge_proposals_pending
+  ON contact_merge_proposals(status)
+  WHERE status = 'pending';
+
+-- ─── Merge Audit ─────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS contact_merge_audit (
+  id                   TEXT PRIMARY KEY,       -- cma-<timestamp_ms>-<random7>
+  canonical_id         TEXT NOT NULL,
+  absorbed_id          TEXT NOT NULL,
+  confidence           REAL NOT NULL,
+  merge_reason         TEXT NOT NULL,
+  triggered_by         TEXT NOT NULL,          -- 'auto' | 'manual'
+  contact_a_snapshot   TEXT NOT NULL,          -- JSON snapshot of canonical before merge
+  contact_b_snapshot   TEXT NOT NULL,          -- JSON snapshot of absorbed before merge
+  merged_at            TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+);
+
+-- ─── Blocklist ───────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS contact_blocklist (
+  contact_id   TEXT PRIMARY KEY REFERENCES contacts(contact_id),
+  reason       TEXT,
+  blocked_by   TEXT NOT NULL DEFAULT 'operator',
+  blocked_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+  unblocked_at TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_blocklist_active
+  ON contact_blocklist(contact_id)
+  WHERE unblocked_at IS NULL;
+
+-- ─── Confirmed Distinct Pairs ────────────────────────────────────────────────
+-- Prevents re-proposing merges that have been explicitly rejected.
+
+CREATE TABLE IF NOT EXISTS contact_confirmed_distinct (
+  id           TEXT PRIMARY KEY,
+  contact_id_a TEXT NOT NULL,
+  contact_id_b TEXT NOT NULL,
+  confirmed_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+  UNIQUE(contact_id_a, contact_id_b)
+);

apsimo/contacts/migrations/002_trust_scopes.sql

@@ -0,0 +1,36 @@
+-- 002_trust_scopes.sql — context-scoped trust (group chats, households, project rooms).
+--
+-- A trust_scope grants its members a tier of trust that applies ONLY inside the
+-- scope. Membership never confers global 1:1 rights (the member's contacts row is
+-- untouched). This is Colony's generic "trusted in this room, not in my DMs" primitive.
+
+CREATE TABLE IF NOT EXISTS trust_scopes (
+  scope_id     TEXT PRIMARY KEY,                 -- ts-<ts>-<rand>
+  scope_type   TEXT NOT NULL DEFAULT 'group'
+               CHECK(scope_type IN ('group','household','project','event','custom')),
+  platform     TEXT,                             -- e.g. 'rcs'; NULL for abstract scopes
+  external_id  TEXT,                             -- platform conversation/group id
+  label        TEXT,
+  granted_tier TEXT NOT NULL DEFAULT 'group_guest'
+               CHECK(granted_tier IN ('inner_circle','trusted','regular','group_guest','peripheral','silenced','acquaintance','unknown')),
+  created_by   TEXT NOT NULL DEFAULT 'agent',
+  active       INTEGER NOT NULL DEFAULT 1 CHECK(active IN (0,1)),
+  created_at   TEXT DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
+  updated_at   TEXT DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
+  UNIQUE(platform, external_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_trust_scopes_extid
+  ON trust_scopes(platform, external_id) WHERE active = 1;
+
+CREATE TABLE IF NOT EXISTS scope_members (
+  scope_id   TEXT NOT NULL REFERENCES trust_scopes(scope_id) ON DELETE CASCADE,
+  contact_id TEXT NOT NULL REFERENCES contacts(contact_id) ON DELETE CASCADE,
+  role       TEXT NOT NULL DEFAULT 'member' CHECK(role IN ('owner','member','observer')),
+  joined_at  TEXT DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
+  left_at    TEXT,                               -- NULL = current member
+  PRIMARY KEY (scope_id, contact_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_scope_members_contact
+  ON scope_members(contact_id) WHERE left_at IS NULL;

apsimo/contacts/migrations/003_open_gateway_enum.sql

@@ -0,0 +1,32 @@
+-- Remove the hardcoded gateway CHECK constraint from contact_handles.
+-- SQLite has no ALTER TABLE DROP CONSTRAINT, so we rebuild the table.
+-- All existing data is preserved; the only change is that gateway now
+-- accepts any string, validated at the application layer.
+
+CREATE TABLE IF NOT EXISTS contact_handles_new (
+    handle_id    TEXT PRIMARY KEY,
+    contact_id   TEXT NOT NULL REFERENCES contacts(contact_id) ON DELETE CASCADE,
+    gateway      TEXT NOT NULL,
+    address      TEXT NOT NULL,
+    is_primary   INTEGER NOT NULL DEFAULT 0
+                   CHECK(is_primary IN (0,1)),
+    verified     INTEGER NOT NULL DEFAULT 0
+                   CHECK(verified IN (0,1)),
+    confidence   REAL NOT NULL DEFAULT 1.0
+                   CHECK(confidence >= 0.0 AND confidence <= 1.0),
+    source       TEXT NOT NULL DEFAULT 'manual',
+    created_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+    UNIQUE(gateway, address)
+);
+
+INSERT OR IGNORE INTO contact_handles_new
+    SELECT handle_id, contact_id, gateway, address,
+           is_primary, verified, confidence, source, created_at
+    FROM contact_handles;
+
+DROP TABLE IF EXISTS contact_handles;
+
+ALTER TABLE contact_handles_new RENAME TO contact_handles;
+
+CREATE INDEX IF NOT EXISTS idx_handles_contact
+    ON contact_handles(contact_id);

apsimo/contacts/migrations/004_contact_provision_operations.sql

@@ -0,0 +1,18 @@
+-- Durable idempotency receipts for owner-operated contact provisioning.
+--
+-- The contact, exact handle, audit rows, and this receipt are committed in one
+-- SQLite transaction by SQLiteContactStore.provision_verified_handle().  A
+-- retry after a lost response therefore returns the original result without
+-- creating a second contact or handle.
+
+CREATE TABLE IF NOT EXISTS contact_provision_operations (
+  operation_id    TEXT PRIMARY KEY,
+  request_sha256  TEXT NOT NULL,
+  performed_by    TEXT NOT NULL,
+  contact_id      TEXT NOT NULL,
+  result_json     TEXT NOT NULL,
+  created_at      TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_contact_provision_operations_contact
+  ON contact_provision_operations(contact_id, created_at DESC);

apsimo/contacts/migrations/005_identity_links.sql

@@ -0,0 +1,27 @@
+-- Candidate associations never participate in message attribution.
+CREATE TABLE IF NOT EXISTS contact_identity_candidates (
+  candidate_id TEXT PRIMARY KEY,
+  contact_id TEXT NOT NULL REFERENCES contacts(contact_id),
+  gateway TEXT NOT NULL,
+  address TEXT NOT NULL,
+  source TEXT NOT NULL,
+  evidence_refs_json TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending','confirmed','rejected')),
+  created_at TEXT NOT NULL,
+  resolved_at TEXT,
+  UNIQUE(contact_id,gateway,address)
+);
+CREATE TABLE IF NOT EXISTS contact_identity_operations (
+  operation_id TEXT PRIMARY KEY,
+  request_sha256 TEXT NOT NULL,
+  result_json TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+-- Retain historical name guesses as candidates rather than usable handles.
+-- Source conversations are not moved or erased by this migration.
+INSERT OR IGNORE INTO contact_identity_candidates
+  (candidate_id,contact_id,gateway,address,source,evidence_refs_json,created_at)
+SELECT 'identity-candidate:' || handle_id,contact_id,gateway,address,source,'[]',created_at
+FROM contact_handles WHERE source='auto:scoped-name' AND verified=0;
+DELETE FROM contact_handles WHERE source='auto:scoped-name' AND verified=0;

apsimo/contacts/models.py

@@ -0,0 +1,308 @@
+"""Colony Contacts — data model dataclasses."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+
+# ── Trust tiers ──────────────────────────────────────────────────────────────
+
+# "group_guest" is a *scoped* tier: it is the trust a person is granted WITHIN a
+# trust_scope (e.g. a group chat) — converse in-context, but no 1:1 DM rights and
+# no proactive reach-out. A contact's global trust_tier is unaffected by it.
+TRUST_TIERS = ("inner_circle", "trusted", "regular", "group_guest", "peripheral", "silenced", "acquaintance", "unknown")
+
+# Higher index = more permissive
+_TIER_RANK = {t: i for i, t in enumerate(("unknown", "acquaintance", "silenced", "peripheral", "group_guest", "regular", "trusted", "inner_circle"))}
+
+PRIVACY_LEVELS = ("public", "private", "restricted")
+GATEWAYS = ("imessage", "telegram", "email", "sms", "signal", "custom", "internal")
+
+# Default interaction_allowed per trust tier (spec §8.1).
+# group_guest is False here because that flag governs *global* (1:1) interaction;
+# in-scope interaction is authorized by the trust_scope, not this flag.
+TIER_DEFAULT_INTERACTION: Dict[str, bool] = {
+    "inner_circle": True,
+    "trusted": True,
+    "regular": True,
+    "group_guest": False,
+    "peripheral": False,
+    "silenced": False,
+    "acquaintance": False,
+    "unknown": True,
+}
+
+
+def more_permissive_tier(a: str, b: str) -> str:
+    """Return the more permissive (higher-ranked) trust tier."""
+    return a if _TIER_RANK.get(a, 0) >= _TIER_RANK.get(b, 0) else b
+
+
+def more_restrictive_privacy(a: str, b: str) -> str:
+    """Return the more restrictive privacy level."""
+    rank = {"public": 0, "private": 1, "restricted": 2}
+    return a if rank.get(a, 1) >= rank.get(b, 1) else b
+
+
+# ── Core entities ─────────────────────────────────────────────────────────────
+
+@dataclass
+class Contact:
+    """A person known to Colony."""
+    contact_id: str
+    display_name: Optional[str]
+    given_name: Optional[str]
+    family_name: Optional[str]
+    organization: Optional[str]
+    relationship_score: float
+    trust_tier: str
+    interaction_allowed: bool
+    tags: List[str]
+    privacy_level: str
+    person_node_id: Optional[str]
+    notes: Optional[str]
+    import_source: str
+    first_seen_at: str
+    last_interaction_at: Optional[str]
+    interaction_count: int
+    enrichment_source: List[str]
+    enrichment_last_at: Optional[str]
+    deleted_at: Optional[str]
+    created_at: str
+    updated_at: str
+    timezone: Optional[str] = None  # IANA tz for this contact (v0.21.0), editable
+    # Introduction provenance (social-graph autonomy): the contact_id of whoever
+    # introduced this person, and a met_via dict ({channel, scope_id, ...}) for
+    # how/where the agent met them. None for contacts not created via an intro.
+    introduced_by: Optional[str] = None
+    met_via: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "contact_id": self.contact_id,
+            "display_name": self.display_name,
+            "given_name": self.given_name,
+            "family_name": self.family_name,
+            "organization": self.organization,
+            "relationship_score": self.relationship_score,
+            "trust_tier": self.trust_tier,
+            "interaction_allowed": self.interaction_allowed,
+            "tags": self.tags,
+            "privacy_level": self.privacy_level,
+            "person_node_id": self.person_node_id,
+            "notes": self.notes,
+            "import_source": self.import_source,
+            "first_seen_at": self.first_seen_at,
+            "last_interaction_at": self.last_interaction_at,
+            "interaction_count": self.interaction_count,
+            "enrichment_source": self.enrichment_source,
+            "enrichment_last_at": self.enrichment_last_at,
+            "deleted_at": self.deleted_at,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "timezone": self.timezone,
+            "introduced_by": self.introduced_by,
+            "met_via": self.met_via,
+        }
+
+    @classmethod
+    def from_row(cls, row: Dict[str, Any]) -> "Contact":
+        tags_json = row.get("tags_json", "[]")
+        tags = json.loads(tags_json) if isinstance(tags_json, str) else (tags_json or [])
+        enrichment_source_json = row.get("enrichment_source", "[]")
+        enrichment_source = (
+            json.loads(enrichment_source_json)
+            if isinstance(enrichment_source_json, str)
+            else (enrichment_source_json or [])
+        )
+        met_via_raw = row.get("met_via_json")
+        met_via = json.loads(met_via_raw) if isinstance(met_via_raw, str) and met_via_raw else None
+        return cls(
+            contact_id=row["contact_id"],
+            display_name=row.get("display_name"),
+            given_name=row.get("given_name"),
+            family_name=row.get("family_name"),
+            organization=row.get("organization"),
+            relationship_score=float(row.get("relationship_score", 0.0)),
+            trust_tier=row.get("trust_tier", "unknown"),
+            interaction_allowed=bool(row.get("interaction_allowed", 1)),
+            tags=tags,
+            privacy_level=row.get("privacy_level", "private"),
+            person_node_id=row.get("person_node_id"),
+            notes=row.get("notes"),
+            import_source=row.get("import_source", "manual"),
+            first_seen_at=row.get("first_seen_at", ""),
+            last_interaction_at=row.get("last_interaction_at"),
+            interaction_count=int(row.get("interaction_count", 0)),
+            enrichment_source=enrichment_source,
+            enrichment_last_at=row.get("enrichment_last_at"),
+            deleted_at=row.get("deleted_at"),
+            created_at=row.get("created_at", ""),
+            updated_at=row.get("updated_at", ""),
+            timezone=row.get("timezone"),
+            introduced_by=row.get("introduced_by"),
+            met_via=met_via,
+        )
+
+
+@dataclass
+class ContactHandle:
+    """A gateway-specific address for a contact."""
+    handle_id: str
+    contact_id: str
+    gateway: str
+    address: str
+    is_primary: bool
+    verified: bool
+    confidence: float
+    source: str
+    created_at: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "handle_id": self.handle_id,
+            "contact_id": self.contact_id,
+            "gateway": self.gateway,
+            "address": self.address,
+            "is_primary": self.is_primary,
+            "verified": self.verified,
+            "confidence": self.confidence,
+            "source": self.source,
+            "created_at": self.created_at,
+        }
+
+    @classmethod
+    def from_row(cls, row: Dict[str, Any]) -> "ContactHandle":
+        return cls(
+            handle_id=row["handle_id"],
+            contact_id=row["contact_id"],
+            gateway=row["gateway"],
+            address=row["address"],
+            is_primary=bool(row.get("is_primary", 0)),
+            verified=bool(row.get("verified", 0)),
+            confidence=float(row.get("confidence", 1.0)),
+            source=row.get("source", "manual"),
+            created_at=row.get("created_at", ""),
+        )
+
+
+@dataclass
+class MergeProposal:
+    """A pending or resolved merge proposal."""
+    id: str
+    contact_id_a: str
+    contact_id_b: str
+    confidence: float
+    reason: str
+    status: str  # pending, approved, rejected, auto_merged
+    proposed_at: str
+    resolved_at: Optional[str]
+
+    @classmethod
+    def from_row(cls, row: Dict[str, Any]) -> "MergeProposal":
+        return cls(
+            id=row["id"],
+            contact_id_a=row["contact_id_a"],
+            contact_id_b=row["contact_id_b"],
+            confidence=float(row["confidence"]),
+            reason=row["reason"],
+            status=row["status"],
+            proposed_at=row["proposed_at"],
+            resolved_at=row.get("resolved_at"),
+        )
+
+
+@dataclass
+class MergeAuditRecord:
+    """Immutable record of a completed merge operation."""
+    audit_id: str
+    canonical_id: str
+    absorbed_id: str
+    confidence: float
+    merge_reason: str
+    triggered_by: str
+    contact_a_snapshot: Dict[str, Any]
+    contact_b_snapshot: Dict[str, Any]
+    merged_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    def __post_init__(self):
+        if self.merged_at is None:
+            self.merged_at = datetime.now(timezone.utc)
+
+
+# ── Trust scopes (context-scoped trust: group chats, households, project rooms) ──
+#
+# A trust_scope grants its members a trust tier that applies ONLY inside the scope
+# (e.g. a specific group conversation). Membership never confers global 1:1 rights —
+# a member's contact.trust_tier / interaction_allowed are independent. This is the
+# generic primitive any agent uses to say "trusted in this room, not in my DMs".
+
+SCOPE_TYPES = ("group", "household", "project", "event", "custom")
+SCOPE_MEMBER_ROLES = ("owner", "member", "observer")
+
+
+@dataclass
+class TrustScope:
+    """A context that grants its members a tier of trust scoped to itself."""
+    scope_id: str
+    scope_type: str                  # one of SCOPE_TYPES
+    platform: Optional[str]          # e.g. "rcs"; NULL for abstract scopes
+    external_id: Optional[str]       # platform conversation/group id (relay conv_id, etc.)
+    label: Optional[str]             # human name (e.g. a group's display name)
+    granted_tier: str                # tier members get WITHIN this scope (default group_guest)
+    created_by: str                  # "owner" | "agent" | contact_id
+    active: bool
+    created_at: str
+    updated_at: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "scope_id": self.scope_id,
+            "scope_type": self.scope_type,
+            "platform": self.platform,
+            "external_id": self.external_id,
+            "label": self.label,
+            "granted_tier": self.granted_tier,
+            "created_by": self.created_by,
+            "active": self.active,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+        }
+
+    @classmethod
+    def from_row(cls, row: Dict[str, Any]) -> "TrustScope":
+        return cls(
+            scope_id=row["scope_id"],
+            scope_type=row["scope_type"],
+            platform=row.get("platform"),
+            external_id=row.get("external_id"),
+            label=row.get("label"),
+            granted_tier=row.get("granted_tier", "group_guest"),
+            created_by=row.get("created_by", "agent"),
+            active=bool(row.get("active", 1)),
+            created_at=row.get("created_at", ""),
+            updated_at=row.get("updated_at", ""),
+        )
+
+
+@dataclass
+class ScopeMember:
+    """A contact's membership in a trust scope (current while left_at is None)."""
+    scope_id: str
+    contact_id: str
+    role: str                        # one of SCOPE_MEMBER_ROLES
+    joined_at: str
+    left_at: Optional[str]
+
+    @classmethod
+    def from_row(cls, row: Dict[str, Any]) -> "ScopeMember":
+        return cls(
+            scope_id=row["scope_id"],
+            contact_id=row["contact_id"],
+            role=row.get("role", "member"),
+            joined_at=row.get("joined_at", ""),
+            left_at=row.get("left_at"),
+        )

apsimo/contacts/scoring.py

@@ -0,0 +1,16 @@
+"""Compatibility for retired composite closeness; historical contact values remain.
+
+Standing, frequency, recency and a contact's affect are not one relationship
+quality. New behavior uses attributed preferences and scoped AppraisalStore views.
+"""
+from typing import Any, Optional
+
+
+def compute_relationship_score(contact: Any, affect_state: Optional[dict] = None, now=None) -> None:
+    """No meaningful scalar is computed. Do not write this into contact storage."""
+    return None
+
+
+def closeness_label(score) -> str:
+    """Old stored values carry no supported psychological interpretation."""
+    return 'legacy score; relationship interpretation unavailable'