From 1fe1193a29744cf7bd26e2a138db047169ecad7c Mon Sep 17 00:00:00 2001 From: Logan Johnson Date: Thu, 10 Sep 2026 00:05:47 -0400 Subject: [PATCH] docs(mobile): document selected mention authorization public API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Answer review 5162334206: document every new public member of SelectedMentionAuthorization — the SelectedMentionKind values (ordinary, agent, unresolvedAgent), the kind and isMember fields, and the requiresAgentAuthorization getter. The docs state that ordinary is the absence of agent evidence, not a humanity claim; that isMember is destination-roster presence at read time only; and that the getter routes evidence evaluation rather than granting a write. Docs comments only; no executable or test change. Signed-off-by: Logan Johnson --- .../selected_mention_authorization.dart | 26 ++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/mobile/lib/shared/mentions/selected_mention_authorization.dart b/mobile/lib/shared/mentions/selected_mention_authorization.dart index a88966fadd..c7ef371088 100644 --- a/mobile/lib/shared/mentions/selected_mention_authorization.dart +++ b/mobile/lib/shared/mentions/selected_mention_authorization.dart @@ -1,14 +1,34 @@ part of 'agent_identity_provider.dart'; /// Evidence requirements, not a claim that an ordinary identity is human. -enum SelectedMentionKind { ordinary, agent, unresolvedAgent } +enum SelectedMentionKind { + /// No fresh agent evidence for this key. Absence of agent evidence, not + /// a humanity claim: the ordinary membership flow applies. + ordinary, + + /// Fresh verified agent evidence for this key: a verified NIP-OA profile + /// owner, a `bot` destination-roster role, or a signature-verified latest + /// kind:10100 runtime event. Evidence only, never permission to write. + agent, + + /// Agent evidence that is not safely established: an invalid profile + /// attestation, an unverifiable latest runtime head, or prior-agent + /// provenance whose fresh evidence is gone. Never demoted to the ordinary + /// flow; carries no agent entry or invitation role. + unresolvedAgent, +} /// Fresh evidence for one exact selected key. This is NOT permission to write: /// consumers must apply their existing agent eligibility evaluator to [agent], /// normal channel invitation permission, consent and scope fences separately. /// An existing member needs no role write, whatever their current role is. class SelectedMentionAuthorization { + /// Fresh evidence classification for this exact key. Values state what + /// fresh evidence showed, never permission, role, or humanity. final SelectedMentionKind kind; + + /// Presence in the destination's signed roster at read time only, not a + /// role, eligibility, or authorization claim. final bool isMember; /// Policy projection with relay-authenticated destination membership only. @@ -18,6 +38,10 @@ class SelectedMentionAuthorization { const SelectedMentionAuthorization._(this.kind, this.isMember, this.agent); + /// True when this key's evidence must be routed through the agent + /// authorization evaluator rather than the ordinary flow: agent or + /// unresolvedAgent evidence. Routing only, never a granted write; + /// eligibility, consent, and invitation fences still apply separately. bool get requiresAgentAuthorization => kind != SelectedMentionKind.ordinary; /// Role selection only, never an invitation authorization. A consumer must