topos-node 1.3.51__tar.gz → 1.3.53__tar.gz

{topos_node-1.3.51/topos_node.egg-info → topos_node-1.3.53}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topos-node
-Version: 1.3.51
+Version: 1.3.53
 Summary: Topos personal AI engine (FastAPI): local data, sync, control plane WebSocket client
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://topos.dialogues.ai
@@ -128,14 +128,6 @@ Topos Engine uses both local and model-hub paths so users can choose flexibility
 
 The `shared/` package in this repo is part of the node runtime contract. It contains common schema and filtering definitions used by both API and engine paths.
 
-### Architecture notes (where truth lives)
-
-This README is orientation, not the architecture ledger. Prefer:
-
-- **As-built / why:** sibling `topos-research-wiki` → `20_ARCHITECTURE/` (`As_Built_Node`, firewall, query, MCP, graph, …)
-- **As-is invariants / checks:** sibling `topos-ops-wiki` → `25_SYSTEMS/` (`SYS-node`, `SYS-cognitive-firewall`, …)
-- **Target design:** `topos-data-wiki` (`status: target`) — do not implement from it without checking as-built
-
 ## Quick Start
 
 ### 1) Install

{topos_node-1.3.51 → topos_node-1.3.53}/README.md

@@ -61,14 +61,6 @@ Topos Engine uses both local and model-hub paths so users can choose flexibility
 
 The `shared/` package in this repo is part of the node runtime contract. It contains common schema and filtering definitions used by both API and engine paths.
 
-### Architecture notes (where truth lives)
-
-This README is orientation, not the architecture ledger. Prefer:
-
-- **As-built / why:** sibling `topos-research-wiki` → `20_ARCHITECTURE/` (`As_Built_Node`, firewall, query, MCP, graph, …)
-- **As-is invariants / checks:** sibling `topos-ops-wiki` → `25_SYSTEMS/` (`SYS-node`, `SYS-cognitive-firewall`, …)
-- **Target design:** `topos-data-wiki` (`status: target`) — do not implement from it without checking as-built
-
 ## Quick Start
 
 ### 1) Install

{topos_node-1.3.51 → topos_node-1.3.53}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "topos-node"
-version = "1.3.51"
+version = "1.3.53"
 description = "Topos personal AI engine (FastAPI): local data, sync, control plane WebSocket client"
 readme = "README.md"
 license = "Apache-2.0"
@@ -128,8 +128,8 @@ filterwarnings = [
   "ignore:on_event is deprecated.*:DeprecationWarning:fastapi.*",
 ]
 markers = [
-  "journey: binds this test to a J-* journey note in topos-ops-wiki (the id is the marker arg)",
-  "check: binds this test to a C-* check note in topos-ops-wiki (the id is the marker arg)",
+  "journey: binds this test to a J-* journey note (the id is the marker arg)",
+  "check: binds this test to a C-* check note (the id is the marker arg)",
   "gap: gap verification test (sprint pack); must pass after sprint lands",
   "qq_eval: live query quality/latency eval against owner database",
   "acceptance: Wiki MVP acceptance test (AT-1 through AT-8)",

{topos_node-1.3.51 → topos_node-1.3.53}/topos/__version__.py

@@ -1,6 +1,6 @@
 """Topos Control Plane Version Information."""
 
-__version__ = "1.3.51"
-__version_info__ = (1, 3, 51)
+__version__ = "1.3.53"
+__version_info__ = (1, 3, 53)
 
 __all__ = ["__version__", "__version_info__"]

{topos_node-1.3.51 → topos_node-1.3.53}/topos/analytics/messenger_communities.py

@@ -448,6 +448,16 @@ def compute_and_persist_messenger_analytics(
         directed_totals["error"] = str(exc)[:200]
     totals.update(directed_totals)
 
+    # The readings lane hangs off this pass rather than off a request: a recompute means
+    # the dyads moved, so the evidence behind every reading may have. Debounced and
+    # single-flight inside; a failure to schedule never fails the analytics.
+    try:
+        from ..features.derivation.person_reading import mark_readings_due
+
+        mark_readings_due(dataset_id)
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("readings not scheduled: %s", exc)
+
     return {
         "dataset_id": dataset_id,
         "period_granularity": period_granularity,

{topos_node-1.3.51 → topos_node-1.3.53}/topos/analytics/person_graph.py

@@ -1183,6 +1183,7 @@ def _merge_appearances(
     participation_total: int,
     *,
     show: int,
+    keep_record_ids: bool = False,
 ) -> Tuple[List[Dict[str, Any]], int]:
     merged: List[Dict[str, Any]] = []
     seen: Set[Tuple[str, str, str]] = set()
@@ -1218,7 +1219,12 @@ def _merge_appearances(
     chosen = merged[:show]
     for row in chosen:
         row.pop("_rich", None)
-        row.pop("record_id", None)
+        # The card's provenance list never wanted the raw id. The reading does: it is the
+        # record its evidence row cites, and without it the reading's provenance ref
+        # collapsed to the subject's spine ref alone (measured 2026-09-05 — every
+        # message-backed evidence row carried a source and no record).
+        if not keep_record_ids:
+            row.pop("record_id", None)
     return chosen, max(total, len(merged))
 
 
@@ -1228,6 +1234,7 @@ def batch_person_appearances(
     *,
     show: int = APPEARANCE_SHOW,
     fetch: int = APPEARANCE_FETCH,
+    keep_record_ids: bool = False,
 ) -> Dict[str, Dict[str, Any]]:
     """Connector-agnostic appearances for many people. Batched IN queries, never N+1.
 
@@ -1247,6 +1254,7 @@ def batch_person_appearances(
             participated.get(nid, []),
             part_totals.get(nid, 0),
             show=show,
+            keep_record_ids=keep_record_ids,
         )
         out[nid] = {
             "mentions": mentions,
@@ -1504,6 +1512,34 @@ def structural_metrics(conn: Any, dataset_id: str, nodes: List[Dict[str, Any]],
         for member in component:
             brokerage_ok[str(member)] = big_enough
 
+    # EXCLUSIVE REACH — what this person is the only way to. Two facts per node, both read
+    # from the tie graph alone (who you know, never shared subjects): the people whose ONLY
+    # connection into your network is this person (their leaf neighbours), and how many
+    # people would lose their path to the rest of their corner if this person were absent
+    # (articulation). Measured on the live node: 74 of 224 structural people are the only
+    # link to at least one other, 48 are articulation points, the largest cut-off is 14.
+    # Orgs and places a person alone carries measured ZERO on the same node — entity_edges
+    # attach them to nobody in the structural set — so that half is not computed, rather
+    # than reported as a confident zero.
+    reach: Dict[str, Dict[str, int]] = {}
+    for component in nx.connected_components(ties):
+        sub = ties.subgraph(component)
+        size = len(component)
+        cut_by: Dict[str, int] = {}
+        if size >= 3:
+            for p in nx.articulation_points(sub):
+                rest = sub.copy()
+                rest.remove_node(p)
+                pieces = sorted((len(c) for c in nx.connected_components(rest)), reverse=True)
+                # everyone outside the largest remaining piece has lost their way to it
+                cut_by[str(p)] = sum(pieces[1:])
+        for p in component:
+            leaves = sum(1 for q in sub.neighbors(p) if sub.degree(q) == 1)
+            cut = cut_by.get(str(p), 0)
+            if leaves or cut:
+                reach[str(p)] = {"exclusive_people": leaves, "cut_off_if_absent": cut,
+                                 "component_size": size}
+
     # Communities from greedy modularity, falling back to connected components — the point
     # is a stable grouping to lay out by, not a claim about social clubs.
     try:
@@ -1561,6 +1597,9 @@ def structural_metrics(conn: Any, dataset_id: str, nodes: List[Dict[str, Any]],
         # A score from a four-person component is arithmetic; the flag says which ones are
         # worth showing as a finding rather than as a number.
         "brokerage_meaningful": brokerage_ok,
+        # Only the nodes with something to say; a missing key means "no exclusive reach",
+        # not "not computed" — every node in `ties` was looked at.
+        "reach": reach,
         "coverage": {
             "basis": ("connections BETWEEN your people, with you removed — you are connected "
                       "to everyone here, so leaving you in makes you the only broker and "
@@ -1570,6 +1609,9 @@ def structural_metrics(conn: Any, dataset_id: str, nodes: List[Dict[str, Any]],
             "communities_from": ("who you know, plus what people have in common — the second "
                                  "is never drawn and never counted as a connection"),
             "centrality_from": "who you know only",
+            "reach_from": ("who you know only — leaf neighbours are people whose sole tie into "
+                           "your network is this person; cut-off counts who would lose their "
+                           "path to the rest of their corner without them"),
             "context_pairs_joined": context_added,
             "excluded": ("semantic similarity between two people is not evidence they know "
                          "each other"),
@@ -2120,6 +2162,124 @@ def attach_coactivity(conn: Any, nodes: List[Dict[str, Any]]) -> Dict[str, int]:
     return {"attached": attached}
 
 
+def person_disposition_facts(conn: Any, nodes: List[Dict[str, Any]]) -> Dict[str, int]:
+    """The owner's informant ratings of a person's Big Five domains, onto their node.
+
+    Only `trait.bfi2_domain` facts whose SUBJECT is this person, and the card labels every
+    one "your read": on this node they are all owner-stated, because the model's estimate
+    is gated behind a validation it has not passed (plan §2.2). Negative Emotionality is
+    named as withheld rather than left blank — a missing slider reads as "not rated yet",
+    a withheld one reads as the decision it is.
+    """
+    by_entity = {str(n["entity_id"]): n for n in nodes if n.get("entity_id") and not n.get("is_owner")}
+    if not by_entity:
+        return {"attached": 0}
+    try:
+        rows = conn.execute(
+            "SELECT payload_json, valid_from FROM signal_objects"
+            " WHERE object_type='fact' AND valid_to IS NULL"
+            " AND payload_json LIKE '%trait.bfi2_domain%'").fetchall()
+    except sqlite3.Error:
+        return {"attached": 0}
+    attached = 0
+    for payload, valid_from in rows:
+        try:
+            fact = json.loads(payload or "{}")
+        except (TypeError, ValueError):
+            continue
+        if str(fact.get("predicate") or "") != "trait.bfi2_domain":
+            continue
+        node = by_entity.get(str(fact.get("subject_entity_id") or ""))
+        if node is None:
+            continue
+        struct = fact.get("value_struct") or fact.get("value") or {}
+        domain, level = str(struct.get("domain") or ""), str(struct.get("level") or "")
+        if not domain or not level:
+            continue
+        disp = node.setdefault("disposition", {
+            "domains": {},
+            "excluded": ["negative_emotionality"],
+            "basis": ("your read — an informant rating you gave on this card; the model's "
+                      "estimate is not shown until it passes validation"),
+        })
+        if domain not in disp["domains"]:
+            attached += 1
+        disp["domains"][domain] = {
+            "level": level,
+            "at": str(valid_from or "")[:10] or None,
+            "stated_by_owner": str(fact.get("asserted_by") or "") == "owner",
+        }
+    return {"attached": attached}
+
+
+def attach_heard_about(conn: Any, dataset_id: str, nodes: List[Dict[str, Any]]) -> Dict[str, int]:
+    """What of the OWNER'S OWN WORK this person has heard about, from the owner's DMs to them.
+
+    The Luck screen already computes this per body of work — "told two people" — and never
+    per person, so a card could not answer the question an ask begins with: can I bring
+    this up without cold-starting? Measured on the live node before this existed: 99
+    owner-authored messages named a work item to 19 people, and none of those 19 cards said
+    so. Reuses the luck rail's resolver end to end rather than a second surface matcher,
+    so the two screens cannot disagree about who has heard what.
+
+    First-party by construction — the events are messages the OWNER wrote (`is_from_self`)
+    in a DM, so this is the owner's record of what they said, never a claim about what the
+    other person knows or repeated. One message is one telling; the chip carries the count
+    and the date so a single mention a year ago reads as exactly that.
+    """
+    from . import luck_surface as L
+
+    for table in ("entity_mentions", "conversation_messages"):
+        if not _appearance_table_exists(conn, table):
+            return {"attached": 0, "events": 0}
+    try:
+        items = L.compile_surfaces(conn, dataset_id, L.build_work_items(conn))
+    except sqlite3.Error:
+        return {"attached": 0, "events": 0}
+    if not items:
+        return {"attached": 0, "events": 0}
+    try:
+        tells = L.build_telling_events(conn, dataset_id, items)
+    except sqlite3.Error:
+        return {"attached": 0, "events": 0}
+    if not tells:
+        return {"attached": 0, "events": 0}
+
+    labels = {i["work_item_id"]: i["label"] for i in items}
+    by_key: Dict[str, Dict[str, Any]] = {}
+    for n in nodes:
+        if n.get("is_owner"):
+            continue
+        for k in n.get("messenger_keys") or []:
+            by_key[str(k)] = n
+    # node_id -> work_item_id -> event times; merged across a person's handles so a person
+    # with two numbers is told once, not twice.
+    merged: Dict[str, Dict[str, List[str]]] = {}
+    for work_item_id, _mid, recipient, _comm, event_at, _period, _n in tells:
+        node = by_key.get(str(recipient))
+        if node is None:
+            continue
+        merged.setdefault(str(node["node_id"]), {}).setdefault(
+            str(work_item_id), []).append(str(event_at or ""))
+    by_node = {str(n["node_id"]): n for n in nodes}
+    attached = 0
+    for node_id, per_item in merged.items():
+        node = by_node.get(node_id)
+        if node is None:
+            continue
+        entries = sorted(((len(times), labels.get(wid, wid), max(times)) for wid, times in per_item.items()),
+                         key=lambda e: (-e[0], e[1]))
+        node["heard_about"] = {
+            "items": [{"label": label, "events": count, "last_at": (last[:10] if last else None)}
+                      for count, label, last in entries[:4]],
+            "events": sum(e[0] for e in entries),
+            "basis": ("your own direct messages to them that name the work — "
+                      "never what they said"),
+        }
+        attached += 1
+    return {"attached": attached, "events": len(tells)}
+
+
 def attach_shared_with_owner(conn: Any, nodes: List[Dict[str, Any]]) -> Dict[str, int]:
     """What the owner and this person BOTH engage with, and what KIND of thing it is.
 

{topos_node-1.3.51 → topos_node-1.3.53}/topos/analytics/relationship_reads.py

@@ -197,9 +197,13 @@ def read_directed_edges(
 
 
 def read_relationship_signals(conn: Any, *, dataset_id: str, signal: str = "all") -> Dict[str, Any]:
-    """The derived read: warmth / drift / reciprocity, calibrated against the owner's own
-    distribution, with what was NOT judged reported rather than hidden."""
-    from ..features.derivation.social_kernels import (_dyad_rows, apply_evidence_floor,
+    """The derived read: warmth / drift / reciprocity / archetype, calibrated against the
+    owner's own distribution, with what was NOT judged reported rather than hidden.
+
+    The archetype reads the directed edges as well as the dyads (766 rows on the live node,
+    one pass, no DDL); it is the one signal that names its unmeasured axes per row."""
+    from ..features.derivation.social_kernels import (_dyad_rows, _edge_rows,
+                                                      apply_evidence_floor, compute_archetype,
                                                       compute_drift, compute_reciprocity,
                                                       compute_warmth)
     from .messenger_directed import MESSENGER_DYAD_STATS_TABLE
@@ -221,11 +225,13 @@ def read_relationship_signals(conn: Any, *, dataset_id: str, signal: str = "all"
         out["drift_alarms"] = compute_drift(rows)
     if signal in ("all", "reciprocity"):
         out["reciprocity"] = compute_reciprocity(rows)
+    if signal in ("all", "archetype"):
+        out["archetypes"] = compute_archetype(rows, _edge_rows(conn, dataset_id))
 
-    labels_for = {r["peer_key"] for k in ("warmth", "drift_alarms", "reciprocity")
+    labels_for = {r["peer_key"] for k in ("warmth", "drift_alarms", "reciprocity", "archetypes")
                   for r in out.get(k, [])}
     labels = peer_labels(conn, dataset_id, sorted(labels_for))
-    for k in ("warmth", "drift_alarms", "reciprocity"):
+    for k in ("warmth", "drift_alarms", "reciprocity", "archetypes"):
         for r in out.get(k, []):
             r["label"] = labels.get(r["peer_key"]) or r["peer_key"]
     return out
@@ -280,7 +286,8 @@ def read_person_graph(conn: Any, *, dataset_id: str,
     """
     from .dataset_resolution import resolve_messaging_dataset
     from .person_graph import (attach_closeness, attach_coactivity, attach_fact_closeness,
-                               attach_shared_with_owner,
+                               attach_heard_about, attach_shared_with_owner,
+                               person_disposition_facts,
                                auto_link_duplicates,
                                build_person_edges, build_person_nodes, group_ambient_people,
                                merge_suggestions, resolve_owner_identity,
@@ -328,6 +335,29 @@ def read_person_graph(conn: Any, *, dataset_id: str,
     # different question of what the two of them WORK ON. Run after the duplicate fold, for
     # the same reason the facts are: the edge must land on the surviving node.
     attach_coactivity(conn, nodes)
+    # What of the owner's OWN work this person has heard about — the owner's DMs to them
+    # that name a body of work, through the luck rail's resolver. Per person here, per
+    # work item there; same events, so the two screens agree.
+    heard_stats = attach_heard_about(conn, dataset_id, nodes)
+    # The owner's informant ratings — stated facts about this person, labelled as such.
+    disposition_stats = person_disposition_facts(conn, nodes)
+    # The commitment ledger, owner's half: what the owner promised this person, in the
+    # owner's own words, and what the record says became of it.
+    from ..features.derivation.commitments import attach_commitments, attach_status_signals
+
+    commitment_stats = attach_commitments(conn, nodes)
+    # What they told you their situation is, in their words, expiring at 90 days.
+    status_stats = attach_status_signals(conn, nodes)
+    # The stored reading, when one exists: computed on the deferred lane, never here.
+    from ..features.derivation.person_reading import load_person_readings
+
+    readings = load_person_readings(conn)
+    for n in nodes:
+        r = readings.get(str(n.get("node_id") or ""))
+        if r:
+            n["reading"] = {k: r.get(k) for k in ("sentences", "strengths", "evidence", "coverage",
+                                                    "computed_at", "model", "reason",
+                                                    "dropped_uncited", "version")}
     # Ambient is 173 of 437 and reads as an undifferentiated fringe, but it holds classical
     # poets, GitHub collaborators, LinkedIn contacts and several pieces of software mistaken
     # for people. Grouping by what each name was seen ALONGSIDE separates them.
@@ -353,6 +383,11 @@ def read_person_graph(conn: Any, *, dataset_id: str,
         n["centrality_degree"] = structure["degree"].get(nid, 0.0)
         n["centrality_betweenness"] = structure["betweenness"].get(nid, 0.0)
         n["brokerage_meaningful"] = bool(structure.get("brokerage_meaningful", {}).get(nid))
+        reach = (structure.get("reach") or {}).get(nid)
+        if reach:
+            # `meaningful` carries the same component-size rule as brokerage: a cut-off
+            # claim inside a four-person corner is arithmetic, a leaf count is a fact.
+            n["reach"] = {**reach, "meaningful": bool(n["brokerage_meaningful"])}
     # People who turn up in the same subjects. A pull on the LAYOUT only: not an edge, not a
     # community, nothing that changes a colour or a count. The graph places people by their
     # relationship to the owner and to each other through messages, and neither of those
@@ -389,6 +424,11 @@ def read_person_graph(conn: Any, *, dataset_id: str,
                             "behaviour understates it, and can only pull someone closer, "
                             "never push them away: silence is not evidence of distance"),
         "fact_closeness_applied": fact_stats.get("applied", 0),
+        "heard_about": heard_stats,
+        "readings": {"attached": sum(1 for n in nodes if n.get("reading"))},
+        "disposition": disposition_stats,
+        "commitments": commitment_stats,
+        "status_signals": status_stats,
         "ambient_groups": {k: ambient_stats.get(k) for k in ("grouped", "ungrouped", "groups")},
         "context_affinity": context["pairs"],
         "context_coverage": context["coverage"],
@@ -423,6 +463,15 @@ def read_person_graph(conn: Any, *, dataset_id: str,
     }
 
 
+def rate_person(conn: Any, *, subject_entity_id: str, domain: str, level: str,
+                note: str = "") -> Dict[str, Any]:
+    """The owner's informant rating of a person's Big Five domain (plan §2.2)."""
+    from ..features.derivation.surfaces import rate_person_disposition
+
+    return rate_person_disposition(conn, subject_entity_id=subject_entity_id,
+                                   domain=domain, level=level, note=note)
+
+
 def read_naming_queue(conn: Any, *, dataset_id: str, limit: int = 25) -> Dict[str, Any]:
     """Unnamed human peers, busiest first."""
     from .dataset_resolution import resolve_messaging_dataset

{topos_node-1.3.51 → topos_node-1.3.53}/topos/api/messenger_analytics.py

@@ -436,6 +436,84 @@ def get_relationship_signals(
     return read_relationship_signals(conn, dataset_id=dataset_id, signal=signal)
 
 
+@router.post("/messenger-analytics/readings/refresh", dependencies=[Depends(require_api_key)])
+def post_readings_refresh(
+    dataset_id: str = Query(...),
+    force: bool = Query(False),
+    limit: int = Query(60, ge=1, le=500),
+) -> Dict[str, Any]:
+    """Run the readings pass now, on a background thread (single-flight). Engine-only."""
+    import threading
+
+    from ..features.derivation import person_reading as PR
+
+    def _go() -> None:
+        from ..core.state import close_thread_db_connection
+
+        with PR._LOCK:
+            if PR._RUNNING:
+                return
+            PR._RUNNING = True
+        try:
+            conn = get_db_connection()
+            if conn is None:
+                return
+            PR._LAST.update(PR.refresh_person_readings(conn, dataset_id, limit=limit, force=force))
+        except Exception as exc:  # noqa: BLE001
+            PR._LAST["error"] = str(exc)[:200]
+        finally:
+            with PR._LOCK:
+                PR._RUNNING = False
+            close_thread_db_connection()
+
+    if PR._RUNNING:
+        return {"status": "running", **PR.readings_status()}
+    t = threading.Thread(target=_go, name="topos-person-readings-manual", daemon=True)
+    t.start()
+    return {"status": "started", "dataset_id": dataset_id, "force": force, "limit": limit}
+
+
+@router.post("/messenger-analytics/commitments/refresh", dependencies=[Depends(require_api_key)])
+def post_commitments_refresh(limit: int = Query(40, ge=1, le=400)) -> Dict[str, Any]:
+    """The commitment ledger's owner half: run `obligations.commitments` over the owner's
+    promise-shaped records only (engine-only; the pack must be enabled by the owner)."""
+    import threading
+
+    from ..features.derivation import commitments as C
+    from ..features.derivation import person_reading as PR
+
+    def _go() -> None:
+        from ..core.state import close_thread_db_connection
+
+        with PR._LOCK:
+            if PR._RUNNING:
+                return
+            PR._RUNNING = True
+        try:
+            conn = get_db_connection()
+            if conn is None:
+                return
+            PR._LAST.update({"commitments": C.refresh_commitments(conn, limit=limit)})
+        except Exception as exc:  # noqa: BLE001
+            PR._LAST["commitments_error"] = str(exc)[:200]
+        finally:
+            with PR._LOCK:
+                PR._RUNNING = False
+            close_thread_db_connection()
+
+    if PR._RUNNING:
+        return {"status": "running", **PR.readings_status()}
+    threading.Thread(target=_go, name="topos-commitments-manual", daemon=True).start()
+    return {"status": "started", "limit": limit}
+
+
+@router.get("/messenger-analytics/readings/status", dependencies=[Depends(require_api_key)])
+def get_readings_status() -> Dict[str, Any]:
+    from ..features.derivation.person_reading import readings_status
+
+    return readings_status()
+
+
 @router.get("/messenger-analytics/bench", dependencies=[Depends(require_api_key)])
 def get_bench() -> Dict[str, Any]:
     conn = get_db_connection()
@@ -517,6 +595,26 @@ def post_person_curate(payload: Dict[str, Any]) -> Dict[str, Any]:
         action=str(payload.get("action") or ""), value=payload.get("value"))
 
 
+@router.post("/messenger-analytics/person-rate", dependencies=[Depends(require_api_key)])
+def post_person_rate(payload: Dict[str, Any]) -> Dict[str, Any]:
+    """The owner's informant rating of a person's Big Five domain — a stated fact through
+    the consent path. 400 with the reason when the rating is refused."""
+    from fastapi import HTTPException
+
+    conn = get_db_connection()
+    if conn is None:
+        return {"error": "no database"}
+    from ..analytics.relationship_reads import rate_person
+
+    try:
+        return rate_person(
+            conn, subject_entity_id=str(payload.get("subject_entity_id") or ""),
+            domain=str(payload.get("domain") or ""), level=str(payload.get("level") or ""),
+            note=str(payload.get("note") or ""))
+    except ValueError as bad:
+        raise HTTPException(status_code=400, detail={"reason": "rating_refused", "error": str(bad)}) from bad
+
+
 @router.post("/messenger-analytics/person-undo", dependencies=[Depends(require_api_key)])
 def post_person_undo(payload: Dict[str, Any]) -> Dict[str, Any]:
     conn = get_db_connection()

{topos_node-1.3.51 → topos_node-1.3.53}/topos/api/signal.py

@@ -1100,13 +1100,23 @@ async def get_derivation_packs(_api_key: str = Depends(require_api_key)):
 async def put_derivation_pack(
     pack_id: str,
     enabled: bool = Body(..., embed=True),
+    consent: bool = Body(False, embed=True),
+    consent_note: str = Body("", embed=True),
     _api_key: str = Depends(require_api_key),
 ):
-    from ..features.derivation.surfaces import set_pack_enabled
+    """Enabling an outward pack (`net_subject: allow`) needs `consent: true`; without it
+    the route answers 409 with the terms the owner must be shown."""
+    from ..features.derivation.surfaces import ConsentRequired, set_pack_enabled
 
-    if not set_pack_enabled(_entities_conn(), pack_id, enabled):
+    try:
+        ok = set_pack_enabled(_entities_conn(), pack_id, enabled,
+                              consent=consent, consent_note=consent_note)
+    except ConsentRequired as need:
+        raise HTTPException(status_code=409, detail={"reason": "consent_required",
+                                                     "terms": need.terms}) from need
+    if not ok:
         raise HTTPException(status_code=404, detail=f"unknown pack {pack_id}")
-    return {"pack_id": pack_id, "enabled": enabled}
+    return {"pack_id": pack_id, "enabled": enabled, "consented": bool(consent and enabled)}
 
 
 @router.get("/facts/conflicts")

{topos_node-1.3.51 → topos_node-1.3.53}/topos/core/handlers/derivation.py

@@ -34,8 +34,17 @@ async def handle_put_derivation_pack(message: Dict[str, Any]) -> Optional[Dict[s
     if not pack_id or not isinstance(enabled, bool):
         return {"id": req_id, "status": "error", "error": "pack_id and enabled (bool) required"}
     try:
-        from ...features.derivation.surfaces import set_pack_enabled
-        if not set_pack_enabled(conn, pack_id, enabled):
+        from ...features.derivation.surfaces import ConsentRequired, set_pack_enabled
+        try:
+            ok = set_pack_enabled(conn, pack_id, enabled,
+                                  consent=bool(payload.get("consent")),
+                                  consent_note=str(payload.get("consent_note") or ""))
+        except ConsentRequired as need:
+            # Not an error in the transport sense: the answer is "show the owner this and
+            # ask". The terms ride back so the client can render them verbatim.
+            return {"id": req_id, "status": "error", "error": str(need),
+                    "reason": "consent_required", "terms": need.terms}
+        if not ok:
             return {"id": req_id, "status": "error", "error": f"unknown pack {pack_id}"}
         return {"id": req_id, "status": "ok",
                 "payload": {"status": "ok", "pack_id": pack_id, "enabled": enabled}}

{topos_node-1.3.51 → topos_node-1.3.53}/topos/core/handlers/messenger_analytics.py

@@ -492,7 +492,8 @@ async def handle_messenger_analytics_periods(message: Dict[str, Any]) -> Optiona
          "messenger_directed_edges", "messenger_bench", "messenger_luck_surface",
          "messenger_person_graph", "messenger_naming_queue",
          "messenger_person_provenance", "messenger_person_curate",
-         "messenger_person_undo", "messenger_curation_history")
+         "messenger_person_undo", "messenger_curation_history",
+         "messenger_person_rate")
 async def handle_relationship_reads(message: Dict[str, Any]) -> Optional[Dict[str, Any]]:
     req_id = message.get("id")
     if not req_id:
@@ -518,7 +519,7 @@ async def handle_relationship_reads(message: Dict[str, Any]) -> Optional[Dict[st
                     "messenger_luck_surface", "messenger_person_graph",
                     "messenger_naming_queue", "messenger_person_provenance",
                     "messenger_person_curate", "messenger_person_undo",
-                    "messenger_curation_history"):
+                    "messenger_curation_history", "messenger_person_rate"):
                 return {"id": req_id, "status": "error", "error": "dataset_id required"}
             if msg_type == "messenger_relationships":
                 result = reads.read_relationships(
@@ -547,6 +548,16 @@ async def handle_relationship_reads(message: Dict[str, Any]) -> Optional[Dict[st
                     conn, dataset_id=dataset_id,
                     subject_ids=payload.get("subject_ids") or payload.get("subject_id") or [],
                     action=str(payload.get("action") or ""), value=payload.get("value"))
+            elif msg_type == "messenger_person_rate":
+                try:
+                    result = reads.rate_person(
+                        conn, subject_entity_id=str(payload.get("subject_entity_id") or ""),
+                        domain=str(payload.get("domain") or ""),
+                        level=str(payload.get("level") or ""),
+                        note=str(payload.get("note") or ""))
+                except ValueError as bad:
+                    return {"id": req_id, "status": "error", "error": str(bad)[:300],
+                            "reason": "rating_refused"}
             elif msg_type == "messenger_person_undo":
                 result = reads.undo_curation(
                     conn, overlay_ids=payload.get("overlay_ids")