Coverage for src/governed_harness/domain/actors.py: 97%
31 statements
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1"""Who may record a human act, and the identity recorded for the person who decides."""
3from __future__ import annotations
5import re
6from typing import Literal
8from .errors import ConfigurationError, NonHumanActorError
10NON_HUMAN_ACTOR_PREFIXES = ("agent.", "validator.", "harness.")
11"""Actor id namespaces the harness assigns to agents, validators and itself."""
13_NON_HUMAN_ACTOR_NAMES = frozenset(prefix.rstrip(".") for prefix in NON_HUMAN_ACTOR_PREFIXES)
15IdentitySource = Literal["explicit", "git", "fallback", "default"]
16"""Where the actor id of a human act came from (``governance.deciderIdentity``)."""
18DEFAULT_CLI_ACTOR = "human.local"
19DEFAULT_API_ACTOR = "human.web"
21_ACTOR_ID = re.compile(r"^[a-z][a-z0-9_.-]{1,127}$")
24def is_non_human_actor_id(actor_id: str) -> bool:
25 normalized = actor_id.strip().lower()
26 return normalized in _NON_HUMAN_ACTOR_NAMES or normalized.startswith(NON_HUMAN_ACTOR_PREFIXES)
29def require_human_actor(actor_id: str, act: str = "record a human decision") -> None:
30 """Refuse an actor id in the namespace of an agent, a validator or the harness itself.
32 The actor id is not authenticated; the check stops a process that runs with the person's
33 terminal (an agent CLI, a validator, the harness) from recording a decision under its own,
34 recognisable identity, as ``task clarify`` already did."""
35 if is_non_human_actor_id(actor_id):
36 raise NonHumanActorError(
37 f"actor {actor_id!r} belongs to the agent, validator or harness namespace "
38 f"({', '.join(NON_HUMAN_ACTOR_PREFIXES)}); only a person may {act}"
39 )
42def actor_id_from_identity(name: str | None, email: str | None) -> str:
43 """A valid actor id for a Git user identity: the e-mail address (or the name) in lower case
44 with every character outside ``[a-z0-9_.-]`` replaced by ``-``."""
45 for source in (email, name):
46 if not source or not source.strip():
47 continue
48 candidate = re.sub(r"[^a-z0-9_.-]+", "-", source.strip().lower())
49 candidate = re.sub(r"^[^a-z]+", "", candidate)[:128].rstrip("-.")
50 if _ACTOR_ID.match(candidate): 50 ↛ 45line 50 didn't jump to line 45 because the condition on line 50 was always true
51 return candidate
52 raise ConfigurationError(
53 "governance.deciderIdentity is git but Git has no usable user.email or user.name; "
54 "set them with git config or pass --actor"
55 )
58def identity_display_name(name: str | None, email: str | None) -> str | None:
59 address = f"<{email.strip()}>" if email and email.strip() else None
60 parts = [part.strip() for part in (name, address) if part and part.strip()]
61 return " ".join(parts) or None