@passioncode-ai/fabric-agent-adapter 0.82.0 → 0.84.1

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_board_link.py

@@ -1,8 +1,10 @@
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 """The board link (DEC-0078, FAA-12b): the board session over the hub, the fsynced checkpoint and a claimed request as
 data. Part of the board connector (FAA-65, layer L4), below the responder in fabric_board_session, which re-exports these
 names. Standard library only, Python 3.9+."""
 from __future__ import annotations
 
+import inspect
 import json
 import math
 import re
@@ -98,17 +100,29 @@ class BoardSession:
         return value
 
     def close(self, timeout: Optional[float] = None) -> bool:
-        """Sends the DELETE (waiting `timeout` seconds at most when above 0, else the session's); True when Fabric answered it with a
+        """Sends the DELETE (waiting `timeout` seconds at most for the whole of it when above 0, FAA-187 (12), else the
+        session's per read); True when Fabric answered it with a
         2xx, so the slots are free now. False otherwise, a 404 (the session was already gone) included: a move made
         before it ended may be read only at the next com.status, so the slot records stay; the lease lapses in 60 s."""
         with self._lock:
             if self.mcp_session is None:
                 return False
+            got: List[Any] = []
+
+            def send() -> None:
+                try:
+                    got.append(self._send({}, method="DELETE", timeout=timeout))
+                except Exception:  # noqa: BLE001 - any failure is no release, as the Node twin's catch reads it
+                    pass
             try:
-                answer = self._send({}, method="DELETE", timeout=timeout)
+                if timeout is not None and timeout > 0:  # the whole DELETE, not each socket read (FAA-187 (12))
+                    worker = threading.Thread(target=send, name="board-leave", daemon=True)
+                    worker.start()
+                    worker.join(timeout)
+                else:
+                    send()
+                answer = got[0] if got else None
                 status = answer[0] if isinstance(answer, (tuple, list)) and answer and isinstance(answer[0], int) else 0
-            except Exception:  # noqa: BLE001 - any failure is no release, as the Node twin's catch reads it
-                status = 0
             finally:
                 self.mcp_session = None  # an answer it cannot read is no release, as the Node twin reads it
             return 200 <= status < 300
@@ -263,6 +277,10 @@ def _bounded_int(literal: str) -> int:
     return int(literal)
 
 
+#: `mandate/1` as a block may write it: its slash plain or JSON-escaped (`\\/`, `\\u002f`).
+_KIND_WRITTEN = re.compile(r"mandate(?:/|\\/|\\u002[fF])1")
+
+
 def read_mandate(request: "BoardRequest", mandate_from: Any, agent_id: Optional[str]) -> Tuple[Optional[Dict[str, Any]], Optional[str]]:
     """The mandate a request carries, read only when the service opted in (`agent_id` and `mandate_from` set), the board
     verified the sender (`provenance: trusted`) and its Project is one `mandate_from` names (or `PERSONAL_BOARD`): a T1
@@ -285,7 +303,7 @@ def read_mandate(request: "BoardRequest", mandate_from: Any, agent_id: Optional[
         try:
             value = json.loads(block, parse_constant=_no_constant, parse_int=_bounded_int)
         except (ValueError, RecursionError):
-            if "mandate/1" in block:
+            if _KIND_WRITTEN.search(block):  # the kind as written, a JSON escape of its slash included (FAA-196 (13))
                 return None, "mandate-unreadable"
             continue
         if isinstance(value, dict) and value.get("kind") == "mandate/1":
@@ -300,9 +318,10 @@ CALL_MEMBERS = ("capability", "action", "effect", "spendUsd", "project")  # what
 
 
 def covers(mandate: Optional[Dict[str, Any]], call: Any, agent_id: Optional[str], wall: Callable[[], float],
-           caller: Any = None) -> Optional[Dict[str, Any]]:
-    """`mandate_covers` for a call under a board request's mandate, its sender placed as T1 and no caller agent id (the
-    board names a Project's principal, not an agent the chain can bind; the chain's end alone binds it, MD-3). A covered
+           caller: Any = None, caller_agent: Optional[str] = None) -> Optional[Dict[str, Any]]:
+    """`mandate_covers` for a call under a board request's mandate, its sender placed as T1. The caller's agent id is
+    `caller_agent`, what the service's identify_agent hook named for the sender (`sender_agent`, FAA-135); without one
+    the chain's end alone binds it (the board names a Project's principal, MD-3). A covered
     answer's `recordAs` names `caller`, the sender Project the board verified (MD-3 records the caller, as the action
     path does). None when no mandate travelled: the handler asks the operator as it would without one. The call's
     `spendUsd` and `project` are read failing closed, as the kit's other mandate readers read them (FAA-139): a spend
@@ -334,12 +353,54 @@ def covers(mandate: Optional[Dict[str, Any]], call: Any, agent_id: Optional[str]
             now = _format_rfc3339(clock * 1000) if math.isfinite(clock) else ""
         except (OverflowError, ValueError):  # finite but outside the dates a clock can name
             now = ""
-    answer = _mandate.mandate_covers({"mandate": mandate, "tier": "T1", "now": now, "self": agent_id, "call": call})
+    inputs = {"mandate": mandate, "tier": "T1", "now": now, "self": agent_id, "call": call}
+    if caller_agent is not None:
+        inputs["callerAgent"] = caller_agent
+    answer = _mandate.mandate_covers(inputs)
     if "recordAs" in answer:
         answer = {"ok": True, "recordAs": dict(answer["recordAs"], caller=caller)}
     return answer
 
 
+def notice_links(links: Any) -> Dict[str, str]:
+    """A responder's `links` (FAA-187 (21)): the page on the service that resolves each notify kind, such as
+    `{"board.slot.moved": "/#board"}`, passed to a notice that notifies as its `link` (events-and-notifications.md).
+    A path on the service, as make_event takes one; None is none. A service that gives links has an emit that takes
+    `link` (JsonlEventLog.append does)."""
+    if links is None:
+        return {}
+    if not isinstance(links, Mapping) or not all(isinstance(k, str) and isinstance(v, str) and v.startswith("/")
+                                                 and not v.startswith("//") for k, v in links.items()):
+        raise BoardError("invalid_arguments", "links maps an event kind to a path on this service, such as /#board.")
+    return dict(links)
+
+
+def read_back_problem(message: Any, entry: Dict[str, Any], project: str) -> Optional[str]:
+    """Why a message read back with com.get is not the request a claim took (the first path refuses it, a resume reads
+    no mandate from it, FAA-196 (1)): `digest-mismatch` (another digest than the claim's), `not-addressed` (not this
+    request, capability and Project), else None."""
+    if not isinstance(message, dict) or message.get("digest") != entry["digest"]:
+        return "digest-mismatch"
+    req = message.get("request")
+    if not isinstance(req, dict) or req.get("id") != entry["request"] or req.get("capability") != entry["capability"] \
+            or req.get("target") != project:
+        return "not-addressed"
+    return None
+
+
+def sender_agent(identify_agent: Optional[Callable[[Any], Optional[str]]], sender: Any, mandate: Any = True) -> Optional[str]:
+    """FAA-135: the agent id the service's identify_agent(sender) names for a request's sender (the board's verified
+    `{project, principal}`), read as the interop kit reads its own hook (`identified_agent`): None is none, an agent id
+    is that id, anything else, or a hook that raises, is an id no chain holds, so the mandate is refused. Asked only
+    when a mandate travelled (`mandate` not None)."""
+    if identify_agent is None or mandate is None:
+        return None
+    try:
+        return _rules.identified_agent(identify_agent(sender))
+    except Exception:  # noqa: BLE001 - the service's own hook: fail closed
+        return _rules.UNREADABLE_AGENT
+
+
 def mandate_options(agent_id: Any, mandate_from: Any) -> Any:
     """The responder's opt-in, checked: an agent id the registry accepts, and `mandate_from` either `PERSONAL_BOARD` or
     a collection of Project ids (strings). Answers `mandate_from` as the responder keeps it (a frozenset or the string)."""
@@ -359,3 +420,31 @@ def mandate_options(agent_id: Any, mandate_from: Any) -> Any:
 def _fold(project: str) -> str:
     """A Project id as Fabric's board compares it: a uuid lower-cased, any other id as written (_hub._project)."""
     return project.lower() if _hub.UUID.fullmatch(project) else project
+
+
+def notice_subject(value: Dict[str, Any], project: str, episode: Optional[str] = None) -> Dict[str, str]:
+    """A notice's subject (`{type, id}`): its request, else its capability, else its episode (a cause such as a block's
+    code, so two causes are two episodes for a host, seam r31), else the Project."""
+    for kind, given in (("request", value.get("request")), ("capability", value.get("capability")), ("episode", episode)):
+        if isinstance(given, str) and 0 < len(given) <= 128:
+            return {"type": kind, "id": given}
+    return {"type": "project", "id": project}
+
+
+def takes_subject(emit: Callable[..., Any]) -> bool:
+    """Whether an emit's signature names a `subject` parameter, as JsonlEventLog.append does. Any other emit (one with
+    only **kwargs, which may forward them to a sink without it or set its own, or one whose signature cannot be read)
+    is called as 0.55.0 called it, without one (0.56.0 unit r33). A subject already bound into the emit, as with
+    functools.partial(log.append, subject=...), stands.
+
+    The signature is the emit's own, not a wrapped function's: a functools.wraps forwarder that sets its own subject
+    would otherwise be passed a second one (0.56.0 unit r34). Nothing here raises, so a notice never stops the
+    responder. A positional-only `subject` cannot take the keyword the responder passes, so it counts as none (FAA-187
+    (26)); the responder's own module imports both helpers under their old private names (moved here in 0.83.0).
+    """
+    try:
+        params = inspect.signature(emit, follow_wrapped=False).parameters.values()
+        return any(p.name == "subject" and p.kind in (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)
+                   and (p.default is inspect.Parameter.empty or p.default is None) for p in params)
+    except Exception:  # noqa: BLE001 - an unreadable signature (or a default that raises) is called without one
+        return False

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_board_session.py

@@ -1,9 +1,9 @@
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 """The board responder (DEC-0078, FAA-12b): the work context a handler sees and the responder loop (enroll, claim,
 accept the exact digest, effect, progress, complete; stop when fenced). The session, the checkpoint and the request live
 in fabric_board_link and are re-exported here. Part of the board connector (FAA-65, layer L4)."""
 from __future__ import annotations
 
-import inspect
 import json
 import random
 import re
@@ -28,6 +28,8 @@ from fabric_board_link import (  # noqa: E402,F401 - re-exported: callers import
     BoardSession,
     Checkpoint,
     PERSONAL_BOARD,
+    notice_subject as _notice_subject,
+    takes_subject as _takes_subject,
 )
 from fabric_board_slots import (  # noqa: E402,F401 - the slot records (FAA-155, FAA-163); the constants re-exported
     HOLD_RETRY_MAX_SECONDS,
@@ -51,6 +53,9 @@ IDLE_LEAVE_SECONDS = 3.0
 
 EVENT_SCHEMA = "urn:fabric:schema:board-responder-event:1"
 
+#: `board.down` is said once per outage window: said again only after the board stayed up this long (FAA-187 (22)).
+DOWN_QUIET_SECONDS = 300.0
+
 #: On these the attempt is no longer ours: stop acting at once (C4).
 STOP_CODES = frozenset(["fenced", "lease_expired", "authority_changed"])
 
@@ -60,8 +65,6 @@ TERMINAL = frozenset(["completed", "failed_known", "cancelled", "expired"])
 NOT_OURS = frozenset(["queued", "claimed", "answered"])
 
 
-
-
 class WorkContext:
     """What a handler may do while it works: `progress(note)` posts a note on the request's thread (and renews the
     lease); `begin_effect(summary)` must be called (and must return) before the handler spends or acts outside
@@ -70,12 +73,12 @@ class WorkContext:
     `mandate_covers(call)` whether it covers a call (`mandate_covers`' answer), None when none travelled."""
 
     def __init__(self, responder: "Responder", entry: Dict[str, Any], mandate: Optional[Dict[str, Any]] = None,
-                 caller: Optional[str] = None):
-        self._responder, self._entry, self.mandate, self._caller = responder, entry, mandate, caller
+                 caller: Optional[str] = None, caller_agent: Optional[str] = None):
+        self._responder, self._entry, self.mandate, self._caller, self._agent = responder, entry, mandate, caller, caller_agent
         self.stopped = threading.Event()
 
     def mandate_covers(self, call: Dict[str, Any]) -> Optional[Dict[str, Any]]:
-        return _link.covers(self.mandate, call, self._responder.agent_id, self._responder.wall, self._caller)
+        return _link.covers(self.mandate, call, self._responder.agent_id, self._responder.wall, self._caller, self._agent)
 
     def progress(self, note: Optional[str] = None) -> None:
         if self.stopped.is_set():
@@ -100,33 +103,6 @@ class _Work:
 Handler = Callable[[BoardRequest, WorkContext], Dict[str, Any]]
 
 
-
-def _notice_subject(value: Dict[str, Any], project: str, episode: Optional[str] = None) -> Dict[str, str]:
-    """A notice's subject (`{type, id}`): its request, else its capability, else its episode (a cause such as a block's
-    code, so two causes are two episodes for a host, seam r31), else the Project."""
-    for kind, given in (("request", value.get("request")), ("capability", value.get("capability")), ("episode", episode)):
-        if isinstance(given, str) and 0 < len(given) <= 128:
-            return {"type": kind, "id": given}
-    return {"type": "project", "id": project}
-
-
-def _takes_subject(emit: Callable[..., Any]) -> bool:
-    """Whether an emit's signature names a `subject` parameter, as JsonlEventLog.append does. Any other emit (one with
-    only **kwargs, which may forward them to a sink without it or set its own, or one whose signature cannot be read)
-    is called as 0.55.0 called it, without one (0.56.0 unit r33). A subject already bound into the emit, as with
-    functools.partial(log.append, subject=...), stands.
-
-    The signature is the emit's own, not a wrapped function's: a functools.wraps forwarder that sets its own subject
-    would otherwise be passed a second one (0.56.0 unit r34). Nothing here raises, so a notice never stops the
-    responder."""
-    try:
-        params = inspect.signature(emit, follow_wrapped=False).parameters.values()
-        return any(p.name == "subject" and p.kind is not inspect.Parameter.VAR_KEYWORD
-                   and (p.default is inspect.Parameter.empty or p.default is None) for p in params)
-    except Exception:  # noqa: BLE001 - an unreadable signature (or a default that raises) is called without one
-        return False
-
-
 class Responder(SlotKeeper):
     """One service's responder for one Project and one or more capabilities, one request at a time.
 
@@ -142,9 +118,11 @@ class Responder(SlotKeeper):
                  emit: Optional[Callable[..., Any]] = None, service: str = "service",
                  now: Callable[[], float] = time.monotonic, rand: Callable[[], float] = random.random,
                  spawn: Optional[Callable[[Callable[[], None]], Any]] = None, session_factory: Optional[Callable[..., BoardSession]] = None,
-                 agent_id: Optional[str] = None, mandate_from: Any = None, wall: Callable[[], float] = time.time):
-        if admit is None or handler is None:
-            raise BoardError("invalid_arguments", "A responder needs the service's own input gate (admit) and a handler.")
+                 agent_id: Optional[str] = None, mandate_from: Any = None, wall: Callable[[], float] = time.time,
+                 identify_agent: Optional[Callable[[Dict[str, Any]], Optional[str]]] = None, links: Any = None):
+        if admit is None or handler is None or not (identify_agent is None or callable(identify_agent)):
+            raise BoardError("invalid_arguments", "A responder needs the service's own input gate (admit) and a handler; "
+                             "identify_agent, when given, is a function of the sender (FAA-135).")
         caps = list(capabilities)
         if not caps or any(not isinstance(c, str) or not _CAPABILITY.fullmatch(c) for c in caps) or len(set(caps)) != len(caps):
             raise BoardError("invalid_arguments", "Name each capability once, [a-z][a-z0-9._-]{1,127}.")
@@ -152,8 +130,10 @@ class Responder(SlotKeeper):
             raise BoardError("invalid_arguments", "%s is a Project's primary responder's, a session's: a service answers "
                              "the capabilities it declares (DEC-0140 PR-1)." % _fs.PRIMARY_CAPABILITY)
         self.hub, self.project = hub, _hub._project(project_id)
-        #: FAA-135: read the operator's mandate from a trusted request of his own Project (opt-in; None reads none).
+        #: FAA-135: read the operator's mandate from a trusted request of his own Project (opt-in; None reads none), and
+        #: bind its chain with the agent id identify_agent names for the sender (asked only when a mandate travelled).
         self.mandate_from, self.agent_id, self.wall = _link.mandate_options(agent_id, mandate_from), agent_id, wall
+        self.identify_agent, self.links = identify_agent, _link.notice_links(links)  # FAA-187 (21): a link per notify kind
         self.capabilities = caps
         self.credential_file, self.handler, self.admit, self.observe = Path(credential_file), handler, admit, observe
         self.checkpoint = Checkpoint(Path(checkpoint_file))
@@ -172,10 +152,12 @@ class Responder(SlotKeeper):
         self.claim_keys: Dict[str, str] = {}
         self._probing: set = set()  # moved slots whose move-back claim lost its answer: asked again under the same key
         self._said: Dict[str, str] = {}
+        self._up_since: Optional[float] = None  # when the board was last seen up after a fault (FAA-187 (22))
         self._rr = 0
         #: The first pause under an operator's hold (DEC-0079); it doubles to HOLD_RETRY_MAX_SECONDS.
         self.hold_delay = POLL_SECONDS
         self._on_hold: set = set()
+        self._taken_back: set = set()  # capabilities the operator took back, not yet held again (FAA-325)
         #: One fenced call at a time, and the entry edits beside them (FAA-77, finding 36).
         self._lock = threading.RLock()
         self._to_resume: List[str] = []  # transferred requests waiting until nothing runs (finding 39)
@@ -203,6 +185,8 @@ class Responder(SlotKeeper):
         # goes once, without a subject there (unit r31, seam r31).
         if _takes_subject(self._emit_to):
             extra["subject"] = _notice_subject(value, self.project, episode)
+        if notify and kind in getattr(self, "links", {}):  # the page that resolves it, which the service named (FAA-187 (21))
+            extra["link"] = self.links[kind]
         try:
             self._emit_to(kind, level, text, notify=notify, **extra)
         except Exception:  # noqa: BLE001 - an event that cannot be written never stops the responder
@@ -267,8 +251,8 @@ class Responder(SlotKeeper):
         self.slots = {}
         self._recover(status, [c for c in self.capabilities if c in grant.capabilities])
         self.state = "ready"
-        for kind in ("board.down", "board.blocked") + (() if missing else ("board.access.needed",)):
-            self._said.pop(kind, None)
+        for kind in ("board.blocked",) + (() if missing else ("board.access.needed",)):
+            self._said.pop(kind, None)  # board.down waits for its quiet window (step)
 
     def _enroll(self, capability: str) -> None:
         args = {"idempotency": self._idem(self._key("enroll")), "capability": capability}
@@ -525,6 +509,8 @@ class Responder(SlotKeeper):
             self.backoff.reset()
             if self.state == "down":  # a lost call was sent again and answered: the session held throughout
                 self.state = "ready"
+            self._up_since = now if self._up_since is None else self._up_since
+            if now - self._up_since >= DOWN_QUIET_SECONDS:  # up a whole window: a later outage is said again
                 self._said.pop("board.down", None)
             return self.interval()
         except (BoardError, _hub.HubError) as exc:
@@ -542,7 +528,7 @@ class Responder(SlotKeeper):
         return min(renewed) + LEASE_SECONDS - self.now() if renewed and self.session is not None else 0.0
 
     def _fault(self, exc: Exception) -> float:
-        code, slots = getattr(exc, "code", "unreachable"), self.slots.values()
+        code, slots, self._up_since = getattr(exc, "code", "unreachable"), self.slots.values(), None
         connecting = self.state == "connecting" and not any(s.get("state") == "held" for s in slots)
         wait = self.backoff.next()
         left = self._lease_left() - LEASE_MARGIN_SECONDS
@@ -613,10 +599,11 @@ class Responder(SlotKeeper):
         for capability in list(self._suspect):  # kept until com.status answered, so it is asked before any enroll
             self._gone(capability)
             self._suspect.discard(capability)
+        shared: Dict[str, Any] = {}  # one com.status read a tick for every moved slot (FAA-194 (5))
         for capability, slot in list(self.slots.items()):
             if slot.get("state") == "moved":  # never enrolled again on its own, even when the new holder lapses (FAA-155)
                 if self.now() - slot.get("renewed_at", 0) >= RENEW_SECONDS - 0.5:
-                    self._moved_back(capability)  # unless com.status shows a later generation it may hold (FAA-165)
+                    self._moved_back(capability, shared)  # unless com.status shows a later generation it may hold (FAA-165)
                 continue
             if slot.get("state") == "paused":
                 if capability != held_by_work and self.now() >= slot.get("retry_at", 0.0) and not self._gone(capability):
@@ -699,15 +686,14 @@ class Responder(SlotKeeper):
                  "revision": receipt["request"]["revision"], "step": "claimed", "keys": {}, "effect": False}
         self.checkpoint.put(entry)
         message = self._call("com.get", {"message": entry["message"]})
-        req = message.get("request") if isinstance(message, dict) else None
-        if message.get("digest") != entry["digest"]:
+        problem = _link.read_back_problem(message, entry, self.project)
+        if problem == "digest-mismatch":
             self.checkpoint.drop(entry["request"])
             self._emit("board.request.skipped", "warning", "A claimed request was not accepted: the message read back carries "
                        "another digest than the claim. Nothing was done; the claim lapses.", request=entry["request"],
                        capability=capability, reason="digest-mismatch")
             return
-        if not isinstance(req, dict) or req.get("id") != entry["request"] or req.get("capability") != capability \
-                or req.get("target") != self.project:
+        if problem:
             self.checkpoint.drop(entry["request"])
             self._emit("board.request.skipped", "warning", "A claimed request was not accepted: it is not addressed to this "
                        "Project and capability. Nothing was done; the claim lapses.", request=entry["request"],
@@ -754,12 +740,15 @@ class Responder(SlotKeeper):
         self.checkpoint.put(entry)
         return True
 
-    def _run(self, entry: Dict[str, Any], request: BoardRequest) -> None:
+    def _run(self, entry: Dict[str, Any], request: BoardRequest, problem: Optional[str] = None) -> None:
         mandate, unread = _link.read_mandate(request, self.mandate_from, self.agent_id)
+        if problem and (mandate is not None or unread):  # FAA-196 (1): a resume read back another message than accepted
+            mandate, unread = None, problem
         if unread:  # by its code alone: the block holds the operator's words
             self._emit("board.request.mandate_unread", "warning", "Request %s carries a mandate the kit does not read (%s); "
                        "it is worked without one." % (entry["request"], unread), request=entry["request"], reason=unread)
-        ctx = WorkContext(self, entry, mandate, request.sender.get("project") if isinstance(request.sender, dict) else None)
+        sender = request.sender if isinstance(request.sender, dict) else {}
+        ctx = WorkContext(self, entry, mandate, sender.get("project"), _link.sender_agent(self.identify_agent, sender, mandate))
         work = _Work(entry, request, ctx)
         work.renewed_at = self.now()
         self.current = work
@@ -781,7 +770,7 @@ class Responder(SlotKeeper):
             self._complete(entry)
             return
         message = self._call("com.get", {"message": entry["message"]})
-        self._run(entry, BoardRequest(message, entry["capability"]))
+        self._run(entry, BoardRequest(message, entry["capability"]), _link.read_back_problem(message, entry, self.project))
 
     def _fenced(self, op: str, entry: Dict[str, Any], key: str, extra: Optional[Dict[str, Any]] = None,
                 apply: Optional[Callable[[Dict[str, Any]], None]] = None) -> Optional[Dict[str, Any]]:

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_board_shapes.py

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 """The project board's wire (fabric-project-comms/0.1, DEC-0022, DEC-0073, DEC-0077): constants, the refusal codes, the
 contract's request digest, the closed shapes the kit reads back (receipts, refusals, directory pages, messages) and
 evidence. Part of the board connector (FAA-65, layer L4)."""

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_board_slots.py

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 """The board responder's slot records (FAA-155, FAA-163): the generation it holds each slot at, a move to another
 session and its take-back, and a capability whose enroll was refused, retried on its own. Part of the board connector
 (FAA-65, layer L4); `Responder` (fabric_board_session) is a `SlotKeeper`."""
@@ -35,6 +36,10 @@ class SlotKeeper:
         self._confirmed[capability] = generation
         self._said.pop("board.slot.refused:" + capability, None)  # held again: a later refusal is said again
         self._said.pop("board.slot.contested:" + capability, None)  # and a later contest, by enroll or replace
+        if capability in self._taken_back:  # FAA-325: held again after the operator's take-back, said once
+            self._taken_back.discard(capability)
+            self._emit("board.slot.returned", "info", "The %s slot on this Project is this service's again: the operator "
+                       "took it back, and it answers it from now on." % capability, capability=capability, generation=generation)
 
     def _note(self, capability: str, record: Optional[Dict[str, Any]]) -> None:
         """The slot record, best effort: one that cannot be written now is written at the next receipt."""
@@ -125,19 +130,20 @@ class SlotKeeper:
                 self._note(capability, dict(held, moved=now))  # said again at the next start if it cannot be written
         if "moved" not in held:  # once, even across restarts
             self._emit("board.slot.moved", "warning", "The %s slot on this Project moved to another session. This service stopped answering it; accepted "
-                       "work stays `accepted` (work begun is the new holder's). The operator brings it back by take-back (once the "
-                       "other session lets it go, or at a restart with accepted work waiting; a restart alone does not) or, where "
-                       "Fabric offers it, a move back here. Else ask its maintainer." % capability,
+                       "work stays accepted (work begun is the new holder's). The operator brings it back by take-back (once the "
+                       "other session lets it go, or at a restart or reconnect with accepted work waiting; neither alone does) or, "
+                       "where Fabric can, a move back here. Else ask its maintainer." % capability,
                        notify=True, episode=capability, capability=capability, generation=now, held=held["generation"])
         return True
 
-    def _moved_back(self, capability: str) -> None:
+    def _moved_back(self, capability: str, shared: Optional[Dict[str, Any]] = None) -> None:
         """A moved slot asked about once per later generation (FAA-165): the operator may move it back to this session
         (DEC-0140 PR-2), which this client cannot hear, so when com.status shows a generation past the recorded move, one
         `com.claim` asks whether the slot is its own. A claim that lands makes it held again and starts what it handed
         out; a `lease_expired` one (the move reached this session but its lease lapsed) enrolls again; a fenced one is
         another session's, recorded so the same generation is not asked about twice. Never an enroll or a replace on a
-        slot another session holds: a slot moved off stays off unless it is handed back."""
+        slot another session holds: a slot moved off stays off unless it is handed back. `shared` holds the tick's one
+        com.status read, shared by every moved slot (FAA-194 (5))."""
         if self.current is not None or self.stopping:
             return  # a claim now could hand out a second request, or start work while the responder stops
         held = self.checkpoint.slots.get(capability) or {}
@@ -145,7 +151,12 @@ class SlotKeeper:
         if held.get("project") != self.project or not _is_int(seen, 1):
             return
         (self.slots.get(capability) or {})["renewed_at"] = self.now()
-        status = self._status()
+        if shared is not None and "status" in shared:
+            status = shared["status"]
+        else:
+            status = self._status()
+            if shared is not None:
+                shared["status"] = status
         now = _whole(next((r.get("generation") for r in status.get("responders") or [] if isinstance(r, dict) and r.get("capability") == capability), None))
         if not _is_int(now, 1) or now <= seen:
             return
@@ -200,9 +211,12 @@ class SlotKeeper:
             if self.checkpoint.slots.get(capability) != held:
                 return False  # take_back (an action thread) forgot the record meanwhile; its own next tick enrolls
             self.slots[capability] = {"state": "held", "generation": generation, "renewed_at": float("-inf")}  # no lease yet
+            self._taken_back.discard(capability)  # said below as a move back, once
             self._held_at(capability, generation)
             self._said.pop("board.slot.moved", None)  # a later move is said again
-        return True
+        self._emit("board.slot.returned", "info", "The %s slot on this Project is this service's again: the operator moved it "
+                   "back here, and it answers it from now on." % capability, capability=capability, generation=generation)
+        return True  # FAA-194 (8): the feed no longer ends on the move's warning
 
     def take_back(self, capability: str) -> None:
         """The operator's act, never the kit's: forget the move; the next tick enrolls once the slot is free (FAA-155)."""
@@ -212,9 +226,12 @@ class SlotKeeper:
             self.checkpoint.slot(capability, None)
             self.claim_keys.pop(capability, None)  # a receipt from before the take-back may be dead
             self._probing.discard(capability)
-            if (self.slots.get(capability) or {}).get("state") == "moved":
+            state = (self.slots.get(capability) or {}).get("state")
+            if state == "moved":
                 self.slots[capability] = {"state": "contested", "renewed_at": 0.0}
             self._said.pop("board.slot.moved", None)
+            if state != "held":  # board.slot.returned is said once the slot is held again (FAA-325); held, nothing to say
+                self._taken_back.add(capability)
 
     # -- one capability's refusal (FAA-163) ------------------------------------------------------------------------
     def _retry_later(self, capability: str, entries: List[Dict[str, Any]], exc: BoardError) -> None:

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_ceremonies.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 """The estate ceremonies' headless join (contract DEC-0084), the Python kit; the Node twin is fabric-ceremonies.mjs.
 Standard library only.
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_connections.py

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 """What an agent uses: `fabric-connections/0.1`, the extension keyed extensions/connections/0.1 (DEC-0096, FAC-SEM-127).
 `connections_view` reads a well-known document as the contract's `connectionsView` does (it never raises);
 `connections_extension` builds the `extensions` entry a service declares, `state` from its own checks and its
@@ -6,7 +7,7 @@ from __future__ import annotations
 
 import re
 import urllib.parse
-from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple
 
 import sys as _sys  # noqa: E402
 from pathlib import Path as _Path  # noqa: E402
@@ -52,7 +53,8 @@ _KEY_SHAPE = re.compile(
     r"(?:^|[^A-Za-z0-9])(?:sk-(?=[A-Za-z0-9_-]*[0-9])(?:(?=[A-Za-z0-9_-]*[A-Z])[A-Za-z0-9_-]{16,}|[A-Za-z0-9_-]{32,})"
     r"|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,}"
     r"|(?:bot)?[0-9]{6,12}:(?=[A-Za-z0-9_-]*[A-Z])(?=[A-Za-z0-9_-]*[a-z])[A-Za-z0-9_-]{34,35}(?![A-Za-z0-9_-]))")
-_URL_SCHEME = re.compile(r"[a-z][a-z0-9+.-]*://", re.IGNORECASE | re.ASCII)
+_SCHEME_LETTERS = frozenset("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ")
+_SCHEME_CHARS = _SCHEME_LETTERS | frozenset("0123456789+.-")
 _CLOSING = ")]}>\"'.,;:!?"
 _TRIED_BACK = 1
 
@@ -139,13 +141,33 @@ def _shape_problems(value: Any) -> List[str]:
     return problems
 
 
+def _scheme_spans(piece: str) -> List[Tuple[int, int]]:
+    """The (start, end) of each URL scheme and its `://` in a piece, where `[a-z][a-z0-9+.-]*://` (case-insensitive,
+    ASCII) finds them left to right, read in linear time (FAA-322: the pattern tried every letter of a long run with no
+    `://`). From each `://` the run of scheme characters before it is read back, and the match starts at its first
+    letter at or after where the last match ended."""
+    spans: List[Tuple[int, int]] = []
+    after, at = 0, piece.find("://")
+    while at >= 0:
+        start = at
+        while start > after and piece[start - 1] in _SCHEME_CHARS:
+            start -= 1
+        while start < at and piece[start] not in _SCHEME_LETTERS:
+            start += 1
+        if start < at:
+            spans.append((start, at + 3))
+            after = at + 3
+        at = piece.find("://", at + 1)
+    return spans
+
+
 def _urls_in(value: str) -> List[str]:
     """The URLs a member may hold, from every scheme in each whitespace-delimited piece, without the closing brackets,
     quotes and punctuation that end a sentence, and with _TRIED_BACK of them put back (`]` closes an IPv6 host)."""
     urls: List[str] = []
     for piece in _SPACES.split(value):
-        for match in _URL_SCHEME.finditer(piece):
-            url = piece[match.start():]
+        for start, _end in _scheme_spans(piece):
+            url = piece[start:]
             end = len(url)
             while end > 0 and url[end - 1] in _CLOSING:
                 end -= 1
@@ -160,8 +182,8 @@ def _long_run(value: str) -> bool:
     """A long secret-shaped run in a piece read whole; in a piece that holds a URL, the text before its first scheme's
     `://` (the URL itself is read by secret_url)."""
     for piece in _SPACES.split(value):
-        found = _URL_SCHEME.search(piece)
-        cut = piece.find("://", found.start()) if found else -1
+        found = _scheme_spans(piece)
+        cut = found[0][1] - 3 if found else -1
         if _long_secret(piece if cut < 0 else piece[:cut]):
             return True
     return False

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_context.py

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 """One instance per context (FAA-125, organization row N-11; contract DEC-0082, "One instance per context on a machine"):
 from a context, ``personal`` or ``org:<orgId>``, the service instance, its folders, descriptor and instance lock. Part of
 the service kit (layer L3, after fabric_descriptor); the twin of fabric-context.mjs. Standard library only.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_crypto.py

@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 """The kit's cryptography, once (FAA-65, layer L1): what the contract's verifiers need and nothing more.
 
 - ``ed25519_verify(public_key, message, signature)`` (RFC 8032) and ``is_small_order_key`` with