@passioncode-ai/passioncode 0.2.45 → 0.2.46

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

@@ -3,6 +3,7 @@ accept the exact digest, effect, progress, complete; stop when fenced). The sess
 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
@@ -26,6 +27,13 @@ from fabric_board_link import (  # noqa: E402,F401 - re-exported: callers import
     BoardSession,
     Checkpoint,
 )
+from fabric_board_slots import (  # noqa: E402,F401 - the slot records (FAA-155, FAA-163); the constants re-exported
+    HOLD_RETRY_MAX_SECONDS,
+    LEASE_MARGIN_SECONDS,
+    SESSION_CODES,
+    SlotKeeper,
+    _whole,
+)
 
 
 RENEW_SECONDS = 20.0
@@ -36,6 +44,9 @@ POLL_JITTER_SECONDS = 5.0
 
 DRAIN_SECONDS = 10.0
 
+#: An idle responder's leave waits this long for the DELETE, so an idle stop ends within LC-01's 5 s (FAA-173).
+IDLE_LEAVE_SECONDS = 3.0
+
 EVENT_SCHEMA = "urn:fabric:schema:board-responder-event:1"
 
 #: On these the attempt is no longer ours: stop acting at once (C4).
@@ -46,11 +57,7 @@ TERMINAL = frozenset(["completed", "failed_known", "cancelled", "expired"])
 #: participant reply (DEC-0098, DEC-0102; not terminal, the requester may still cancel it, and nobody claims it).
 NOT_OURS = frozenset(["queued", "claimed", "answered"])
 
-#: A lost call is sent again this long before the lease it keeps would lapse (FAA-77, finding 38).
-LEASE_MARGIN_SECONDS = 10.0
 
-#: How long a held slot waits before it asks again: doubling from the poll interval, never past this.
-HOLD_RETRY_MAX_SECONDS = 900.0
 
 
 class WorkContext:
@@ -84,10 +91,35 @@ class _Work:
 
 Handler = Callable[[BoardRequest, WorkContext], Dict[str, Any]]
 
-_whole = lambda v: int(v) if isinstance(v, float) and v.is_integer() else v  # noqa: E731 - 2.0 is 2, as Node reads it
 
 
-class Responder:
+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.
 
     `handler(request, ctx)` returns the outcome `{state, observed?, summary?, evidence?, reply?}`; `admit(request)`
@@ -132,21 +164,31 @@ class Responder:
         self._lock = threading.RLock()
         self._to_resume: List[str] = []  # transferred requests waiting until nothing runs (finding 39)
         self._suspect: set = set()  # capabilities a fenced call was refused on: com.status says whether they moved (FAA-155)
+        self._confirmed: Dict[str, Any] = {}  # this session's: the generation it held, or com.status showed unmoved
 
     # -- events -------------------------------------------------------------------------------------------------
-    def _emit(self, kind: str, level: str, text: str, notify: bool = False, episode: Optional[str] = None, **value: Any) -> None:
-        if episode is not None:
-            if self._said.get(kind) == episode:
+    def _emit(self, kind: str, level: str, text: str, notify: bool = False, episode: Optional[str] = None,
+              said_as: Optional[str] = None, **value: Any) -> None:
+        if episode is not None:  # `said_as` keeps one episode per key, such as one per capability
+            key = said_as or kind
+            if self._said.get(key) == episode:
                 return  # once per episode
-            self._said[kind] = episode
+            self._said[key] = episode
         data = {"schema": EVENT_SCHEMA, "value": {k: v for k, v in value.items() if v is not None}}
         problems = _fs.feed_data_problems(data)
         if problems:  # FAC-SEM-101: never a credential in data; drop the data, keep the sentence
             data = None
         if self._emit_to is None:
             return
+        # The thing the notice is about, so a host tells one request's or one capability's episode from another's
+        # (events-and-notifications.md, "Say who wants what"; 0.56.0 seam r30).
+        extra = {"data": data} if data else {}
+        # An emit written before 0.56.0 may take no subject: read from its signature, never from an error, so a notice
+        # goes once, without a subject there (unit r31, seam r31).
+        if _takes_subject(self._emit_to):
+            extra["subject"] = _notice_subject(value, self.project, episode)
         try:
-            self._emit_to(kind, level, text, notify=notify, **({"data": data} if data else {}))
+            self._emit_to(kind, level, text, notify=notify, **extra)
         except Exception:  # noqa: BLE001 - an event that cannot be written never stops the responder
             pass
 
@@ -193,6 +235,8 @@ class Responder:
 
     def _connect(self) -> None:
         self.state = "connecting"
+        self.slots = {}  # the previous session's slots are not this one's: a refusal now reconnects (FAA-163)
+        self._confirmed = {}  # nor its confirmations: a slot may have moved between the two sessions
         grant = self.hub.join_board(self.project, self.credential_file)
         missing = [c for c in self.capabilities if c not in grant.capabilities]
         session = self.session_factory(grant)
@@ -200,7 +244,7 @@ class Responder:
         self.session = session
         status = self._status()
         if missing:
-            self._emit("board.access.needed", "warn", "The operator has not let this service answer %s on this Project; ask in "
+            self._emit("board.access.needed", "warning", "The operator has not let this service answer %s on this Project; ask in "
                        "Fabric (Agents & access)." % ", ".join(missing), notify=True, episode=",".join(missing),
                        capabilities=missing)
         self.slots = {}
@@ -221,14 +265,14 @@ class Responder:
                 if self._gone(capability):
                     return
                 self.slots[capability] = {"state": "contested", "renewed_at": self.now()}
-                self._emit("board.slot.contested", "warn", "Another responder holds the %s slot on this Project; this service "
+                self._emit("board.slot.contested", "warning", "Another responder holds the %s slot on this Project; this service "
                            "waits for it to lapse and never takes it over by itself." % capability, notify=True,
-                           episode=capability, capability=capability)
+                           episode=capability, said_as="board.slot.contested:" + capability, capability=capability)
                 return
             raise
         self.slots[capability] = {"state": "held", "generation": receipt["slot"]["generation"], "renewed_at": self.now()}
         self._held_at(capability, receipt["slot"]["generation"])
-        self._said.pop("board.slot.contested", None)
+        self._said.pop("board.slot.contested:" + capability, None)
         self._lifted(capability)
 
     def _pause(self, capability: str) -> None:
@@ -248,108 +292,6 @@ class Responder:
             self._emit("board.slot.released", "info", "The operator's hold on %s was lifted; the service takes new work "
                        "again." % capability, capability=capability)
 
-    # -- a slot moved to another session (FAA-155, DEC-0140 PR-2) ------------------------------------------------
-    def _held_at(self, capability: str, generation: int) -> None:
-        """The generation this responder holds the slot at, kept beside its checkpoint so a restart knows it."""
-        self._note(capability, {"project": self.project, "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."""
-        try:
-            self.checkpoint.slot(capability, record)
-        except BoardError:
-            pass
-
-    def _ask(self, capability: str, op: str, args: Dict[str, Any]) -> Dict[str, Any]:
-        """An enroll or replace that can move the generation is recorded with its key first (a lost answer is no move)."""
-        held = self.checkpoint.slots.get(capability) or {}
-        if held.get("project") != self.project:
-            return self._call(op, args)  # no record: nothing a lost answer could be mistaken for
-        slot = self.slots.get(capability) or {}
-        if op == "com.enroll" and slot.get("state") == "held" and slot.get("generation") == held.get("generation") \
-                and self.now() - slot.get("renewed_at", 0.0) < LEASE_SECONDS - LEASE_MARGIN_SECONDS and "asking" not in held:
-            return self._call(op, args)  # a live holder's renew cannot change its generation: nothing to record
-        if isinstance(held.get("asking"), dict):
-            if self._gone(capability):  # an earlier lost ask is settled first; it may show the slot moved
-                raise BoardError("fenced", "The %s slot moved to another session." % capability, op=op)
-            held = self.checkpoint.slots.get(capability) or {}
-        try:
-            self.checkpoint.slot(capability, dict(held, asking={"op": op, "args": args}))
-            return self._call(op, args)
-        except BoardError as exc:
-            if exc.code == "checkpoint":
-                return self._call(op, args)
-            if exc.code not in ("unreachable", "session-ended"):
-                self._note(capability, held)
-            raise
-
-    def _replay(self, capability: str, held: Dict[str, Any], before: Any) -> Dict[str, Any]:
-        """Asks a lost enroll or replace again under its key. `repeated: true`: the generation is ours. Else it ran only now: past
-        a move (`before` beyond the record) the move is read. A refusal drops the record; a lost answer keeps it."""
-        asking = held.get("asking")
-        rest = {k: v for k, v in held.items() if k != "asking"}
-        if isinstance(asking, dict) and asking.get("op") in ("com.enroll", "com.responder_replace"):
-            try:
-                answer = self._receipt(asking["op"], self._call(asking["op"], asking.get("args")))
-                generation, moved = _whole(answer["slot"]["generation"]), _is_int(before, 1) and before > rest.get("generation", before)
-                if _is_int(generation, 1) and (answer.get("repeated") is True or not moved):
-                    rest = {"project": self.project, "generation": generation}
-            except BoardError as exc:
-                if exc.code in ("unreachable", "session-ended"):
-                    raise
-                if exc.code == "idempotency_window_expired":
-                    rest = {}  # a retired epoch refuses even a repeat: unknown, so no record (a first start, never a move)
-            except (KeyError, TypeError):
-                pass
-        self._note(capability, rest or None)
-        return rest
-
-    def _gone(self, capability: str, status: Optional[Dict[str, Any]] = None) -> bool:
-        """True when `com.status` shows the slot's generation past the record (the slot is left `moved`); else False."""
-        held = self.checkpoint.slots.get(capability) or {}
-        if held.get("project") != self.project or (not _is_int(held.get("generation"), 1) and "asking" not in held):
-            return False
-        status = self._status() if status is None else status
-        now = _whole(next((r.get("generation") for r in status.get("responders") or [] if isinstance(r, dict) and r.get("capability") == capability), None))
-        held = self._replay(capability, held, now) if "asking" in held else held  # its own lost ask first
-        if "moved" in held and _is_int(held.get("moved"), 1) and not (_is_int(now, 1) and now > held.get("generation", now)):
-            now = held["moved"]  # a recorded move stays until take_back, whatever com.status says of the slot now
-        if not _is_int(now, 1) or not _is_int(held.get("generation"), 1) or now <= held["generation"]:
-            return False
-        with self._lock:
-            work = self.current
-            if work is not None and work.entry["capability"] == capability:
-                work.ctx.stopped.set()
-                self.current = None
-            for entry in [dict(e) for e in self.checkpoint.entries.values() if e.get("capability") == capability]:
-                if entry.get("step") == "claimed":
-                    self.checkpoint.drop(entry["request"])  # the move returned the claim to the queue
-                elif entry.get("step") not in ("unknown", "lapsed"):
-                    # Begun: outcome_unknown, which the slot's holder reconciles. Accepted: held on the board, continued only
-                    # by a transfer if the slot is this service's again; never a com.responder_replace on its own.
-                    entry["step"] = "unknown" if entry.get("effect") else "lapsed"
-                    self.checkpoint.put(entry)
-            self._to_resume = [r for r in self._to_resume if (self.checkpoint.entries.get(r) or {}).get("capability") != capability]
-            self.slots[capability] = {"state": "moved", "generation": now, "renewed_at": self.now()}
-        if "moved" not in held:  # once, even across restarts
-            self._emit("board.slot.moved", "warn", "The %s slot on this Project was moved to another session. This service stopped "
-                       "answering it there, left its accepted work held (work already begun is the new holder's to settle) and does not "
-                       "take the slot back by itself. Its take-back action brings it back once the other session lets it go; without one, ask its "
-                       "maintainer." % capability,
-                       notify=True, episode=capability, capability=capability, generation=now, held=held["generation"])
-            self._note(capability, dict(held, moved=now))  # said again at the next start if it cannot be written
-        return True
-
-    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)."""
-        if capability not in self.capabilities:
-            raise BoardError("invalid_arguments", "This responder does not answer %s." % capability)
-        with self._lock:
-            self.checkpoint.slot(capability, None)
-            if (self.slots.get(capability) or {}).get("state") == "moved":
-                self.slots[capability] = {"state": "contested", "renewed_at": 0.0}
-            self._said.pop("board.slot.moved", None)
-
     # -- restart: reconcile and transfer -------------------------------------------------------------------------
     def _read_state(self, entry: Dict[str, Any]) -> Optional[str]:
         message = self._call("com.get", {"message": entry["message"]})
@@ -381,26 +323,40 @@ class Responder:
         responders = [r for r in status.get("responders") or [] if isinstance(r, dict)]
         generations = {r.get("capability"): _whole(r.get("generation", 0)) for r in responders}
         on_hold = {r.get("capability") for r in responders if r.get("held") is True}  # DEC-0079
+        failure: Optional[BoardError] = None
         for capability in capabilities:
             held, was = transfer.get(capability), (self.checkpoint.slots.get(capability) or {}).get("generation")
-            if self._gone(capability, status):
-                continue  # moved away: never replaced at recovery (FAA-155)
-            if capability in on_hold:
-                for entry in held or []:
-                    entry["step"] = "lapsed"  # taken back by a transfer once the hold is lifted
-                    self.checkpoint.put(entry)
-                self._pause(capability)
-            elif held:  # at the generation a replay of its own lost ask just recorded, else com.status's (seam 6)
-                mine = (self.checkpoint.slots.get(capability) or {}).get("generation")
-                self._replace(capability, held, mine if _is_int(mine, 1) and mine != was else generations.get(capability, 0))
-            else:
-                self._enroll(capability)
+            if failure is not None:  # the board session failed: the rest wait for the next tick (FAA-163)
+                self._retry_later(capability, held or [], failure)
+                self._suspect.add(capability)  # its move check comes before its retry enrolls (0.56.0 seam r2)
+                continue
+            try:
+                self._settle(capability, lambda: self._recover_one(capability, status, held, was, generations, on_hold), held)
+            except BoardError as exc:
+                failure = exc
         for entry in reconcile:
             if self.slots.get(entry["capability"], {}).get("state") == "held":
                 self._reconcile(entry)
             elif entry.get("step") != "unknown":
                 entry["step"] = "unknown"  # the slot is not this session's yet: a later tick reconciles it (finding 38)
                 self.checkpoint.put(entry)
+        if failure is not None:
+            raise failure
+
+    def _recover_one(self, capability: str, status: Dict[str, Any], held: Optional[List[Dict[str, Any]]], was: Any,
+                     generations: Dict[Any, Any], on_hold: set) -> None:
+        if self._gone(capability, status):
+            return  # moved away: never replaced at recovery (FAA-155)
+        if capability in on_hold:
+            for entry in held or []:
+                entry["step"] = "lapsed"  # taken back by a transfer once the hold is lifted
+                self.checkpoint.put(entry)
+            self._pause(capability)
+        elif held:  # at the generation a replay of its own lost ask just recorded, else com.status's (seam 6)
+            mine = (self.checkpoint.slots.get(capability) or {}).get("generation")
+            self._replace(capability, held, mine if _is_int(mine, 1) and mine != was else generations.get(capability, 0))
+        else:
+            self._enroll(capability)
 
     def _replace(self, capability: str, entries: List[Dict[str, Any]], generation: Any) -> None:
         if not _is_int(generation, 0):
@@ -432,7 +388,7 @@ class Responder:
                 # start (or the operator) decides.
                 entry["step"] = "held"
                 self.checkpoint.put(entry)
-                self._emit("board.request.held", "warn", "An accepted request could not be resumed: this Fabric does not hand "
+                self._emit("board.request.held", "warning", "An accepted request could not be resumed: this Fabric does not hand "
                            "back a transferred attempt (DEC-0078). It stays held; nothing was done.", notify=True,
                            episode=entry["request"], request=entry["request"], capability=capability)
                 continue
@@ -517,7 +473,7 @@ class Responder:
         if outcome is None:
             entry["step"] = "unknown"
             self.checkpoint.put(entry)
-            self._emit("board.reconcile.needed", "warn", "A request's outcome is unknown: the work may have happened. It stays "
+            self._emit("board.reconcile.needed", "warning", "A request's outcome is unknown: the work may have happened. It stays "
                        "unknown until this service observes what happened.", notify=True, episode=entry["request"],
                        request=entry["request"], capability=entry["capability"])
             return
@@ -559,7 +515,8 @@ class Responder:
     def _lease_left(self) -> float:
         """Seconds this session's leases still run, by its own clock: the running attempt's, else the oldest held slot's."""
         renewed = [self.current.renewed_at or 0.0] if self.current is not None else \
-            [s.get("renewed_at", 0.0) for s in self.slots.values() if s.get("state") == "held"]
+            [s.get("renewed_at", 0.0) for s in self.slots.values() if s.get("state") == "held"
+             and s.get("renewed_at", 0.0) != float("-inf")]  # a lapsed slot holds no lease (FAA-163)
         return min(renewed) + LEASE_SECONDS - self.now() if renewed and self.session is not None else 0.0
 
     def _fault(self, exc: Exception) -> float:
@@ -574,7 +531,7 @@ class Responder:
         if code in ("not_authorized", "authority_changed", "credential"):
             self.state = "not-authorized"
             self._drop_session()
-            self._emit("board.access.needed", "warn", "This service may not answer requests for this Project: the operator "
+            self._emit("board.access.needed", "warning", "This service may not answer requests for this Project: the operator "
                        "has to allow it in Fabric (Agents & access). Nothing is claimed until then.", notify=True,
                        episode="access", reason=code)
         elif code == "held":
@@ -592,10 +549,16 @@ class Responder:
             # In recovery with no slot held a refusal reconnects (seam 6); with some held they are served (seam 7).
             if (connecting or code in ("session-ended", "unreachable", "not-running", "not-a-hub", "hub-unavailable", "protocol")) and not keep:
                 self._drop_session()
-            self._emit("board.down", "warn", "Fabric's board cannot be reached; the responder tries again with a growing pause.",
+            self._emit("board.down", "warning", "Fabric's board cannot be reached; the responder tries again with a growing pause.",
                        episode="down", reason=code)
         return wait
 
+    def _held(self) -> Dict[str, Any]:
+        """The generations this session confirmed (held, or compared with com.status and found unmoved), paused and
+        retrying slots included: only their records a clean leave may forget (0.56.0 seam r2, r3)."""
+        return {c: g for c, g in dict(self._confirmed).items()  # a fenced call (maybe moved) or a move withholds it
+                if c not in self._suspect and (self.slots.get(c) or {}).get("state") != "moved"}
+
     def _drop_session(self) -> None:
         work, self.current, self._to_resume = self.current, None, []  # the next session transfers them again
         if work is not None:
@@ -610,8 +573,8 @@ class Responder:
             else:
                 work.ctx.stopped.set()  # the lease lapses; acting on would outlive the attempt
         session, self.session = self.session, None
-        if session is not None:
-            session.close()
+        if session is not None and session.close():
+            self.checkpoint.leave(self.project, self._held())  # the DELETE released them: a standby taking one is no move
 
     def _tick(self) -> None:
         work = self.current
@@ -628,8 +591,12 @@ class Responder:
             if slot.get("state") == "moved":
                 continue  # never enrolled again on its own, even when the new holder's lease lapses (FAA-155)
             if slot.get("state") == "paused":
-                if capability != held_by_work and self.now() >= slot.get("retry_at", 0.0):
-                    self._enroll(capability)  # still held: a longer pause; lifted: the slot is ours again
+                if capability != held_by_work and self.now() >= slot.get("retry_at", 0.0) and not self._gone(capability):
+                    self._enroll(capability)  # still held: a longer pause; lifted: the slot is ours again (moved: read first)
+                continue
+            if slot.get("state") == "retry":  # its enroll was refused: asked again alone (FAA-163)
+                if self.now() >= slot.get("retry_at", 0.0):
+                    self._settle(capability, lambda: self._gone(capability) or self._enroll(capability))
                 continue
             if capability != held_by_work and self.now() - slot.get("renewed_at", 0) >= RENEW_SECONDS - 0.5:
                 self._enroll(capability)  # the holder's enroll renews its lease (no event); a lapsed one re-enrolls
@@ -707,14 +674,14 @@ class Responder:
         req = message.get("request") if isinstance(message, dict) else None
         if message.get("digest") != entry["digest"]:
             self.checkpoint.drop(entry["request"])
-            self._emit("board.request.skipped", "warn", "A claimed request was not accepted: the message read back carries "
+            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:
             self.checkpoint.drop(entry["request"])
-            self._emit("board.request.skipped", "warn", "A claimed request was not accepted: it is not addressed to this "
+            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"],
                        capability=capability, reason="not-addressed")
             return
@@ -819,7 +786,7 @@ class Responder:
             if entry.get("effect"):
                 entry["step"] = "unknown"
                 self.checkpoint.put(entry)
-                self._emit("board.reconcile.needed", "warn", "The attempt was lost after its effect began; the outcome stays "
+                self._emit("board.reconcile.needed", "warning", "The attempt was lost after its effect began; the outcome stays "
                            "unknown until this service observes what happened.", notify=True, episode=entry["request"],
                            request=entry["request"], capability=entry["capability"], reason=code)
             elif entry.get("step") not in ("claimed", "accepting") and (code == "lease_expired" or (
@@ -828,13 +795,13 @@ class Responder:
                 # it (C4). It continues only by a checkpoint transfer to this responder while it holds the slot.
                 entry["step"] = "lapsed"
                 self.checkpoint.put(entry)
-                self._emit("board.attempt.lost", "warn", ("This service's lease on an accepted request lapsed; it stopped working "
+                self._emit("board.attempt.lost", "warning", ("This service's lease on an accepted request lapsed; it stopped working "
                            "on it and takes it back by a transfer." if code == "lease_expired" else "The board fenced an accepted "
                            "request away from this service; it stopped working on it, and nothing had been done outside it."),
                            request=entry["request"], capability=entry["capability"], reason=code)
             else:
                 self.checkpoint.drop(entry["request"])
-                self._emit("board.attempt.lost", "warn", "The board took a request back from this service (%s); it stopped working "
+                self._emit("board.attempt.lost", "warning", "The board took a request back from this service (%s); it stopped working "
                            "on it, and nothing had been done outside the service." % code, request=entry["request"],
                            capability=entry["capability"], reason=code)
 
@@ -910,7 +877,7 @@ class Responder:
                        "summary": "The service could not do this (%s)." % work.failure.__class__.__name__}
         problems = outcome_problems(outcome, bool(entry.get("effect")))
         if problems:
-            self._emit("board.outcome.invalid", "warn", "The handler's outcome was not sent: %s." % problems[0],
+            self._emit("board.outcome.invalid", "warning", "The handler's outcome was not sent: %s." % problems[0],
                        request=entry["request"], capability=entry["capability"])
             if entry.get("effect"):
                 self._settle_live(entry, "observation_required" if any("observation_required" in p for p in problems) else "outcome")
@@ -994,7 +961,8 @@ class Responder:
             except (BoardError, _hub.HubError):
                 pass  # the checkpoint keeps it
         if self.session is not None:
-            self.session.close()
-            self.session = None
-            self.checkpoint.leave(self.project)  # the slots were released: no record of them can read as a move
+            session, self.session = self.session, None
+            # Only a DELETE Fabric answered released the slots (FAA-163); an idle stop waits for it 3 s (FAA-173).
+            if session.close(IDLE_LEAVE_SECONDS if work is None else None):
+                self.checkpoint.leave(self.project, self._held())  # no record of them can read as a move
         self.state = "stopped"

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

@@ -0,0 +1,173 @@
+"""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`."""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import sys as _sys  # noqa: E402
+from pathlib import Path as _Path  # noqa: E402
+if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from any working directory (FAA-65)
+    _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+from fabric_board_shapes import BoardError, LEASE_SECONDS, _is_int  # noqa: E402 - the kit (FAA-65)
+
+#: A lost call is sent again this long before the lease it keeps would lapse (FAA-77, finding 38).
+LEASE_MARGIN_SECONDS = 10.0
+
+#: How long a held slot waits before it asks again: doubling from the poll interval, never past this.
+HOLD_RETRY_MAX_SECONDS = 900.0
+
+#: Refusals that are about the board session, not one capability: they end recovery and go to the responder's fault.
+SESSION_CODES = frozenset(["unreachable", "session-ended", "not_authorized", "authority_changed", "credential", "no-epoch",
+                           "schema-unsupported", "checkpoint", "receipt-shape", "idempotency_conflict", "not-running",
+                           "not-a-hub", "hub-unavailable", "protocol", "not_available"])
+
+_whole = lambda v: int(v) if isinstance(v, float) and v.is_integer() else v  # noqa: E731 - 2.0 is 2, as Node reads it
+
+
+class SlotKeeper:
+    """The slot methods of `Responder`, which owns every attribute they read (`checkpoint`, `slots`, `project`, `_lock`)."""
+
+    # -- a slot moved to another session (FAA-155, DEC-0140 PR-2) ------------------------------------------------
+    def _held_at(self, capability: str, generation: int) -> None:
+        """The generation this responder holds the slot at, kept beside its checkpoint so a restart knows it."""
+        self._note(capability, {"project": self.project, "generation": generation})
+        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
+
+    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."""
+        try:
+            self.checkpoint.slot(capability, record)
+        except BoardError:
+            pass
+
+    def _ask(self, capability: str, op: str, args: Dict[str, Any]) -> Dict[str, Any]:
+        """An enroll or replace that can move the generation is recorded with its key first (a lost answer is no move)."""
+        held = self.checkpoint.slots.get(capability) or {}
+        if held.get("project") != self.project:
+            return self._call(op, args)  # no record: nothing a lost answer could be mistaken for
+        slot = self.slots.get(capability) or {}
+        if op == "com.enroll" and slot.get("state") == "held" and slot.get("generation") == held.get("generation") \
+                and self.now() - slot.get("renewed_at", 0.0) < LEASE_SECONDS - LEASE_MARGIN_SECONDS and "asking" not in held:
+            return self._call(op, args)  # a live holder's renew cannot change its generation: nothing to record
+        if isinstance(held.get("asking"), dict):
+            if self._gone(capability):  # an earlier lost ask is settled first; it may show the slot moved
+                raise BoardError("fenced", "The %s slot moved to another session." % capability, op=op)
+            held = self.checkpoint.slots.get(capability) or {}
+        try:
+            self.checkpoint.slot(capability, dict(held, asking={"op": op, "args": args}))
+            return self._call(op, args)
+        except BoardError as exc:
+            if exc.code == "checkpoint":
+                return self._call(op, args)
+            if exc.code not in ("unreachable", "session-ended"):
+                self._note(capability, held)
+            raise
+
+    def _replay(self, capability: str, held: Dict[str, Any], before: Any) -> Dict[str, Any]:
+        """Asks a lost enroll or replace again under its key. `repeated: true`: the generation is ours. Else it ran only now: past
+        a move (`before` beyond the record) the move is read. A refusal drops the record; a lost answer keeps it."""
+        asking = held.get("asking")
+        rest = {k: v for k, v in held.items() if k != "asking"}
+        if isinstance(asking, dict) and asking.get("op") in ("com.enroll", "com.responder_replace"):
+            try:
+                answer = self._receipt(asking["op"], self._call(asking["op"], asking.get("args")))
+                generation, moved = _whole(answer["slot"]["generation"]), _is_int(before, 1) and before > rest.get("generation", before)
+                if _is_int(generation, 1) and (answer.get("repeated") is True or not moved):
+                    rest = {"project": self.project, "generation": generation}
+            except BoardError as exc:
+                if exc.code in ("unreachable", "session-ended"):
+                    raise
+                if exc.code == "idempotency_window_expired":
+                    rest = {}  # a retired epoch refuses even a repeat: unknown, so no record (a first start, never a move)
+            except (KeyError, TypeError):
+                pass
+        self._note(capability, rest or None)
+        return rest
+
+    def _gone(self, capability: str, status: Optional[Dict[str, Any]] = None) -> bool:
+        """True when `com.status` shows the slot's generation past the record (the slot is left `moved`); else False."""
+        held = self.checkpoint.slots.get(capability) or {}
+        if held.get("project") != self.project or (not _is_int(held.get("generation"), 1) and "asking" not in held):
+            return False
+        status = self._status() if status is None else status
+        now = _whole(next((r.get("generation") for r in status.get("responders") or [] if isinstance(r, dict) and r.get("capability") == capability), None))
+        held = self._replay(capability, held, now) if "asking" in held else held  # its own lost ask first
+        if "moved" in held and _is_int(held.get("moved"), 1) and not (_is_int(now, 1) and now > held.get("generation", now)):
+            now = held["moved"]  # a recorded move stays until take_back, whatever com.status says of the slot now
+        if not _is_int(now, 1) or not _is_int(held.get("generation"), 1) or now <= held["generation"]:
+            if _is_int(now, 1) and _is_int(held.get("generation"), 1) and "moved" not in held:
+                self._confirmed[capability] = held["generation"]  # com.status shows it unmoved (0.56.0 seam r3)
+            return False
+        with self._lock:
+            record = self.checkpoint.slots.get(capability) or {}
+            if record.get("project") != self.project or record.get("generation") != held.get("generation"):
+                return False  # take_back (an action thread) forgot the record meanwhile: no move to keep (FAA-158)
+            work = self.current
+            if work is not None and work.entry["capability"] == capability:
+                work.ctx.stopped.set()
+                self.current = None
+            for entry in [dict(e) for e in self.checkpoint.entries.values() if e.get("capability") == capability]:
+                if entry.get("step") == "claimed":
+                    self.checkpoint.drop(entry["request"])  # the move returned the claim to the queue
+                elif entry.get("step") not in ("unknown", "lapsed"):
+                    # Begun: outcome_unknown, which the slot's holder reconciles. Accepted: held on the board, continued only
+                    # by a transfer if the slot is this service's again; never a com.responder_replace on its own.
+                    entry["step"] = "unknown" if entry.get("effect") else "lapsed"
+                    self.checkpoint.put(entry)
+            self._to_resume = [r for r in self._to_resume if (self.checkpoint.entries.get(r) or {}).get("capability") != capability]
+            self.slots[capability] = {"state": "moved", "generation": now, "renewed_at": self.now()}
+            self._confirmed.pop(capability, None)
+            if "moved" not in held:
+                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 there and left its "
+                       "accepted work `accepted` (work begun is the new holder's to settle). Its take-back action brings the "
+                       "slot back once the other session lets it go, or at a later restart or reconnect while accepted work "
+                       "waits; a restart alone does not. Without it, ask its maintainer." % capability,
+                       notify=True, episode=capability, capability=capability, generation=now, held=held["generation"])
+        return True
+
+    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)."""
+        if capability not in self.capabilities:
+            raise BoardError("invalid_arguments", "This responder does not answer %s." % capability)
+        with self._lock:
+            self.checkpoint.slot(capability, None)
+            if (self.slots.get(capability) or {}).get("state") == "moved":
+                self.slots[capability] = {"state": "contested", "renewed_at": 0.0}
+            self._said.pop("board.slot.moved", None)
+
+    # -- one capability's refusal (FAA-163) ------------------------------------------------------------------------
+    def _retry_later(self, capability: str, entries: List[Dict[str, Any]], exc: BoardError) -> None:
+        """An enroll or replace of one capability was refused: its accepted work waits `lapsed` (a transfer takes it
+        back once the slot is held) and the capability asks again after a doubling pause; the others go on. A refusal
+        of the board session (SESSION_CODES) is not this capability's: it is left to retry and nothing is said, since
+        the responder's fault says the board is down."""
+        if (self.slots.get(capability) or {}).get("state") == "held":
+            return  # the replace landed: what failed came after it
+        for entry in entries:
+            if entry.get("step") not in ("unknown", "lapsed"):
+                entry["step"] = "lapsed"
+                self.checkpoint.put(entry)
+        slot = self.slots.get(capability) or {}
+        tries = slot.get("tries", 0) + 1 if slot.get("state") == "retry" else 1
+        wait = min(HOLD_RETRY_MAX_SECONDS, self.hold_delay * 2 ** (tries - 1))
+        self.slots[capability] = {"state": "retry", "tries": tries, "retry_at": self.now() + wait, "renewed_at": self.now()}
+        if exc.code not in SESSION_CODES:  # once per episode (said_as), also after a silent session refusal
+            self._emit("board.slot.refused", "warning", "Fabric refused to give this service the %s slot (%s); it asks again "
+                       "later. Its other capabilities go on." % (capability, exc.code), episode=capability,
+                       said_as="board.slot.refused:" + capability,
+                       capability=capability, reason=exc.code)
+
+    def _settle(self, capability: str, act, entries: Optional[List[Dict[str, Any]]] = None) -> None:
+        """Runs one capability's enroll or replace (FAA-163). A refusal of the board session is raised after the
+        capability is left to retry; any other leaves it to retry and the next capability goes on."""
+        try:
+            act()
+        except BoardError as exc:
+            self._retry_later(capability, entries or [], exc)
+            if exc.code in SESSION_CODES:
+                raise