@passioncode-ai/fabric-agent-adapter 0.61.0 → 0.63.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/support-agent/channel-agent.example.json

@@ -0,0 +1,103 @@
+{
+  "https://fabric.passioncode.ai/agent-contract/extensions/channel-agent/0.1": {
+    "standard": "channel-agent-standard/1",
+    "projects": [
+      {
+        "project": "project:example-shop",
+        "side": "example-side",
+        "lead_agent": "example-agent",
+        "adopted_at": "2026-11-10",
+        "taxonomy": {
+          "version": "2026-11-04",
+          "codes": [
+            {
+              "code": "orders.status",
+              "label": "Where is my order"
+            },
+            {
+              "code": "payments.refund",
+              "label": "A refund"
+            }
+          ]
+        },
+        "tiers": [
+          {
+            "code": "premium",
+            "label": "Premium",
+            "rule": "open_orders > 10",
+            "escalate": "at_once"
+          }
+        ],
+        "question_route": {
+          "capability": "operator.ask",
+          "target": "00000000-0000-4000-8000-000000000001",
+          "daily_cap": 10,
+          "days": "mon-fri",
+          "tz": "Europe/Warsaw",
+          "send_at": "09:00",
+          "expires": "P7D"
+        },
+        "gap_registry": {
+          "none": "not_yet",
+          "until": "2026-11-30"
+        },
+        "channels": [
+          {
+            "id": "mail",
+            "kind": "mail",
+            "replies_enabled": true,
+            "decision": null,
+            "final_limit": "P7D",
+            "first_reply_limit": "PT24H",
+            "holding_reply": true,
+            "clarifying_question": true,
+            "quiet_window": null,
+            "late_answer_window": null,
+            "items_seen_unit": "mails",
+            "texts": {
+              "holding": {
+                "en": "Thank you, we are looking into it and will answer here."
+              },
+              "final": {
+                "en": "Here is the answer to your question. Write again if anything is still unclear."
+              }
+            }
+          }
+        ],
+        "sources": [
+          {
+            "id": "knowledge",
+            "owner": "example-agent",
+            "read": "file",
+            "cadence": "PT1H",
+            "max_age": "PT2H"
+          }
+        ],
+        "declined_sources": [],
+        "handoff_queues": [
+          {
+            "id": "support-mailbox",
+            "owner": "example-team",
+            "limit": "P2D",
+            "answered_signal": "none",
+            "recommendation": "5d1f0a3c-8b2e-4c7a-9e6f-1a2b3c4d5e6f"
+          }
+        ],
+        "evals": {
+          "suite": "test/evals/support",
+          "judge_budget_usd": 0,
+          "replay_budget_usd": 0,
+          "spend_record": null
+        },
+        "tickets": {
+          "outbox": "state/tickets-outbox.jsonl",
+          "token_slot": "example-shop/prod/SIGNAL_TICKETS_TOKEN",
+          "pd_check": {
+            "none": "not_used"
+          }
+        },
+        "recorded_decisions": []
+      }
+    ]
+  }
+}

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/support-agent/config.example.json

@@ -1,5 +1,6 @@
 {
   "knowledge": "knowledge.example.json",
+  "knowledgeMaxAgeSeconds": 7200,
   "stateDir": "state",
   "model": "deepseek/deepseek-v4.1-flash",
   "fallback": "qwen/qwen3.8-flash",

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/support-agent/support_agent.py

@@ -24,8 +24,9 @@ For each message it:
 What the agent does not do: send the reply anywhere (the service that calls it owns its channel), judge facts with a
 model, or answer outside the knowledge file. The model's text is data: a citation it invents fails the check.
 
-The kit modules (fabric_openrouter and its closure) sit beside this file in a service
-(`fabric_kit.py install <dir> --module fabric_openrouter`); in this repository they are read from ../../scripts.
+The kit modules sit beside this file in a service, installed as the README's "Install into a service" says
+(`fabric_kit.py install <dir> --lang py --module fabric_openrouter --module fabric_usage --module fabric_paths
+--module fabric_connections`); in this repository they are read from ../../scripts.
 Standard library only. FAA-65 REQ-09.
 """
 from __future__ import annotations
@@ -38,8 +39,9 @@ import re
 import secrets
 import sys
 import threading
+import time
 from pathlib import Path
-from typing import Any, Callable, Dict, List, Mapping, Optional
+from typing import Any, Callable, Dict, List, Mapping, Optional, Tuple, Union
 
 if str(Path(__file__).resolve().parent) not in sys.path:  # the kit installed beside it, under `python3 -I` too
     sys.path.insert(0, str(Path(__file__).resolve().parent))
@@ -127,6 +129,25 @@ def words(text: str) -> set:
     return {w for w in (m.lower() for m in _WORD.findall(text)) if len(w) > 1 and w not in STOPWORDS}
 
 
+#: How deep the knowledge file may nest (the file, its entries list, an entry, a member): far past any real entry.
+MAX_KNOWLEDGE_DEPTH = 32
+
+
+def _depth(value: Any) -> int:
+    """How deep a parsed JSON value nests, walked without recursion."""
+    deepest, stack = 0, [(value, 1)]
+    while stack:
+        item, level = stack.pop()
+        deepest = max(deepest, level)
+        if level > MAX_KNOWLEDGE_DEPTH:
+            return level
+        if isinstance(item, dict):
+            stack.extend((child, level + 1) for child in item.values())
+        elif isinstance(item, list):
+            stack.extend((child, level + 1) for child in item)
+    return deepest
+
+
 class Knowledge:
     """Entries `{id, question, answer, tags?}` from a JSON file (`{"entries": [...]}`); ids are unique."""
 
@@ -137,14 +158,28 @@ class Knowledge:
                 raise RecipeError("every knowledge entry has an id of letters, digits, '.', '_', ':' or '-'")
             if not isinstance(entry.get("answer"), str) or not entry["answer"].strip():
                 raise RecipeError("knowledge entry %s has no answer" % entry["id"])
+            if "question" in entry and not isinstance(entry["question"], str):
+                raise RecipeError("knowledge entry %s has a question that is not text" % entry["id"])
+            tags = entry.get("tags", [])
+            if not isinstance(tags, list) or not all(isinstance(tag, str) for tag in tags):
+                raise RecipeError("knowledge entry %s has tags that are not a list of text" % entry["id"])
             if entry["id"] in self.entries:
                 raise RecipeError("knowledge entry %s appears twice" % entry["id"])
             self.entries[entry["id"]] = dict(entry)
 
     @classmethod
     def load(cls, path: Path) -> "Knowledge":
-        data = json.loads(Path(path).read_text(encoding="utf-8"))
-        return cls(data.get("entries", []) if isinstance(data, dict) else [])
+        try:
+            data = json.loads(Path(path).read_text(encoding="utf-8"))
+        except RecursionError:
+            raise RecipeError("the knowledge file is nested too deep to read") from None
+        except ValueError:  # not JSON at all: refused like every other wrong shape, its content never quoted
+            raise RecipeError("the knowledge file %s is not JSON" % Path(path).name) from None
+        if not isinstance(data, dict) or not isinstance(data.get("entries"), list):
+            raise RecipeError("the knowledge file is an object with an `entries` list")  # never an empty set by mistake
+        if _depth(data) > MAX_KNOWLEDGE_DEPTH:  # the same verdict on every Python, whatever its parser's own limit
+            raise RecipeError("the knowledge file is nested too deep to read")
+        return cls(data["entries"])
 
     def lookup(self, question: str, limit: int = 3) -> List[Dict[str, Any]]:
         """The entries sharing the most words with the question (its words against each entry's question, tags and
@@ -160,6 +195,52 @@ class Knowledge:
         return [entry for _, _, entry in sorted(scored)[:limit]]
 
 
+class KnowledgeSource:
+    """The knowledge file as a declared source (the channel-agent standard's 7.1 and 7.4, FAA-197): read again when the
+    file changes, the last good version kept when a read fails (`degraded` until a good one), and `stale` past
+    `max_age_s`. The age is the last good version's: from its file's modification time, so a file nobody rebuilt ages
+    however often it is looked at, and a restart does not make old content new. The calling service shows `state()`
+    and opens one alert when it is stale."""
+
+    def __init__(self, path: Path, *, max_age_s: int, clock: Callable[[], float] = time.time):
+        if isinstance(max_age_s, bool) or not isinstance(max_age_s, int) or max_age_s < 1:
+            raise RecipeError("max_age_s is a whole number of seconds, at least 1")
+        self.path, self.max_age_s, self._clock = Path(path), max_age_s, clock
+        self._knowledge: Optional[Knowledge] = None
+        self._good_mtime = 0.0
+        self._seen: Optional[Tuple[int, int, int, int]] = None
+        self._degraded = False
+
+    def current(self) -> Knowledge:
+        try:  # the time, the size, the inode and the status-change time, which no copy or `touch -r` can set back: a
+            # rewrite in one coarse tick, a copy that kept the time, or (on POSIX with fine timestamps) one in place
+            # with the same size still shows; on Windows st_ctime is the creation time and catches no such rewrite
+            stat = self.path.stat()
+            seen: Optional[Tuple[int, int, int, int]] = (stat.st_mtime_ns, stat.st_size, stat.st_ino, stat.st_ctime_ns)
+        except OSError:
+            seen = None
+        if self._knowledge is not None and seen is not None and seen == self._seen:
+            return self._knowledge  # unchanged since this version was read (or failed to read)
+        try:
+            knowledge = Knowledge.load(self.path)
+        except (OSError, ValueError, RecursionError, RecipeError) as err:  # RecursionError: JSON nested too deep
+            if self._knowledge is None:
+                if isinstance(err, RecipeError):  # read, and refused: its message names the entry (ids are safe text)
+                    raise
+                raise RecipeError("the knowledge file %s could not be read (%s)" % (self.path.name,
+                                                                                   err.__class__.__name__))
+            self._seen, self._degraded = seen, True
+        else:
+            self._knowledge, self._seen, self._degraded = knowledge, seen, False
+            self._good_mtime = seen[0] / 1e9 if seen is not None else self._clock()
+        return self._knowledge
+
+    def state(self) -> Dict[str, Any]:
+        age = max(0, int(self._clock() - self._good_mtime)) if self._knowledge is not None else None
+        return {"id": "knowledge", "age_s": age, "max_age_s": self.max_age_s,
+                "stale": age is None or age > self.max_age_s, "degraded": self._degraded}
+
+
 def _currency(unit: str) -> str:
     unit = unit.lower()
     return "rub" if unit.startswith("руб") else _CURRENCY.get(unit, unit)
@@ -240,6 +321,22 @@ SYSTEM = (
 )
 
 
+#: The channel-agent standard's 4.4 (FAA-197): a draft the checks refused is rewritten once with the refusal's reason.
+REPAIR_NOTE = ("Your reply was refused by the checks: {reasons}. Write it again from the same entries only, keeping "
+               "every rule above, or answer exactly HANDOFF.")
+
+
+def repairable(decision: Any) -> bool:
+    """A hand-off the code checks made, with the draft they refused: no-knowledge, model-unsure and model:* are not."""
+    if not isinstance(decision, Mapping) or decision.get("action", "handoff") != "handoff" or decision.get("fallback"):
+        return False  # a fallback already had its one repair
+    reasons = decision.get("reasons")
+    draft = decision.get("draft")
+    return (isinstance(draft, str) and bool(draft.strip()) and isinstance(reasons, list) and bool(reasons)
+            and all(isinstance(r, str) and r != "no-knowledge" and r != "model-unsure" and not r.startswith("model:")
+                    for r in reasons))
+
+
 def entry_text(entry: Mapping[str, Any]) -> str:
     return "\n".join([str(entry.get("question", "")), str(entry["answer"]), " ".join(map(str, entry.get("tags", [])))])
 
@@ -356,7 +453,7 @@ def prune(state_dir: Path, keep_days: int, *, now: Optional[datetime] = None) ->
 
 
 class SupportAgent:
-    def __init__(self, *, knowledge: Knowledge, client: Any, model: str, fallback: str, state_dir: Path,
+    def __init__(self, *, knowledge: Union[Knowledge, "KnowledgeSource"], client: Any, model: str, fallback: str, state_dir: Path,
                  max_tokens: int = 600, max_chars: int = 1200, lookup_limit: int = 3,
                  on_handoff: Optional[Callable[[Dict[str, Any]], None]] = None):
         self.knowledge, self.client = knowledge, client
@@ -371,6 +468,22 @@ class SupportAgent:
         self._local = threading.local()
         self._log = DecisionLog(self.state_dir)
 
+    def connections(self) -> List[Dict[str, Any]]:
+        """FAA-199: what the agent uses, for `connections_extension` in the well-known document of the service that runs
+        it (DEC-0096); that service adds its own hand-off route and channels."""
+        # A model id that is not one (empty, missing, with a space) is left out, so a misconfigured fallback degrades the
+        # replies, never the well-known document (0.62.0 seam reading 1).
+        named = [("model", self.model, "drafts replies from the knowledge file"),
+                 ("fallback", self.fallback, "drafts when the first model fails")]
+        import fabric_connections  # the service that declares them installs it (README); the agent runs without it
+        kept = []
+        for ident, target, purpose in named:  # by the connections rule itself, never a second copy of it (seam reading 2)
+            item = {"id": ident, "kind": "model", "target": target, "purpose": purpose}
+            probe = {"extensions": {fabric_connections.CONNECTIONS_EXTENSION_KEY: {"connections": [dict(item, state="unknown")]}}}
+            if not fabric_connections.connections_rules(probe):
+                kept.append(item)
+        return kept
+
     @property
     def decisions_file(self) -> Path:
         return self._log.path
@@ -378,7 +491,8 @@ class SupportAgent:
     def _outbox(self, decision: Dict[str, Any]) -> None:
         # The outbox keeps the customer's own text until it is pruned: see `prune` and the README's retention note.
         fabric_paths.ensure_private_dir(self.state_dir)
-        line = json.dumps(decision, ensure_ascii=False, separators=(",", ":")) + "\n"
+        kept = {k: v for k, v in decision.items() if k != "draft"}  # a person reads the question and the reasons
+        line = json.dumps(kept, ensure_ascii=False, separators=(",", ":")) + "\n"
         _append_line(self.state_dir / "handoffs.jsonl", line.encode("utf-8"))
 
     def prune(self, keep_days: int, *, now: Optional[datetime] = None) -> Dict[str, int]:
@@ -388,12 +502,22 @@ class SupportAgent:
             self._log = DecisionLog(self.state_dir)
         return removed
 
-    def answer(self, message_id: str, text: str, *, task_run_id: Optional[str] = None) -> Dict[str, Any]:
-        """The decision for one message: `{messageId, action: reply|handoff, reply?, citations, reasons, costUsd}`."""
+    def answer(self, message_id: str, text: str, *, task_run_id: Optional[str] = None,
+               repair: Optional[Mapping[str, Any]] = None) -> Dict[str, Any]:
+        """The decision for one message: `{messageId, action: reply|handoff, reply?, citations, reasons, costUsd}`; a
+        hand-off the checks made also carries the refused `draft`. `repair=` that decision (under a new message id)
+        rewrites the draft once with the refusal's reasons: a pass is a reply with `repaired: true`, and a repair that
+        does not end in a reply (a second refusal, a model `HANDOFF`, no knowledge on the retry; not a `model:*`
+        outage) a hand-off with `fallback: true` (the channel-agent standard's 4.4 and 13.2, FAA-197)."""
         if not isinstance(message_id, str) or not _ID.fullmatch(message_id):
             raise RecipeError("message id: letters, digits, '.', '_', ':' or '-', up to 128")
         if not isinstance(text, str) or not text.strip():
             raise RecipeError("the message has no text")
+        if repair is not None and not repairable(repair):
+            raise RecipeError("repair= takes a hand-off the checks made, with its draft and reasons: the first call's "
+                              "decision or the on_handoff copy (a repeat returns no draft, and a fallback had its repair)")
+        if repair is not None and repair.get("messageId") == message_id:
+            raise RecipeError("repair= runs under a new message id: the refused one returns its stored decision")
         if getattr(self._local, "in_handoff", False):
             raise ReentryError("answer() was called from on_handoff: queue the hand-off and call answer() again after "
                               "this call returns")
@@ -402,7 +526,7 @@ class SupportAgent:
             done = self._log.get(message_id)
             if done is not None:
                 return dict(done, repeated=True)
-            decision = self._decide(message_id, text, task_run_id)
+            decision = self._decide(message_id, text, task_run_id, repair)
             at = _now()
             if decision["action"] == "handoff":  # before the decision is saved: a crash repeats a handoff, never loses one
                 self._local.in_handoff = True
@@ -410,27 +534,38 @@ class SupportAgent:
                     self.on_handoff(dict(decision, question=text, at=_stamp(at)))
                 finally:
                     self._local.in_handoff = False
-            self._log.append(decision, at)
+            self._log.append({k: v for k, v in decision.items() if k != "draft"}, at)  # the draft is never stored
         return dict(decision, repeated=False)
 
-    def _decide(self, message_id: str, text: str, task_run_id: Optional[str]) -> Dict[str, Any]:
+    def _decide(self, message_id: str, text: str, task_run_id: Optional[str],
+                repair: Optional[Mapping[str, Any]] = None) -> Dict[str, Any]:
         base = {"messageId": message_id, "citations": [], "costUsd": None}
-        entries = self.knowledge.lookup(text, self.lookup_limit)
+        knowledge = self.knowledge.current() if isinstance(self.knowledge, KnowledgeSource) else self.knowledge
+        entries = knowledge.lookup(text, self.lookup_limit)
         if not entries:
-            return dict(base, action="handoff", reasons=["no-knowledge"])
+            gone = dict(base, action="handoff", reasons=["no-knowledge"])
+            return dict(gone, fallback=True) if repair is not None else gone
+        messages = build_messages(text, entries)
+        if repair is not None:
+            messages += [{"role": "assistant", "content": repair["draft"]},
+                         {"role": "user", "content": REPAIR_NOTE.format(reasons=", ".join(repair["reasons"]))}]
         try:
-            got = self.client.chat(build_messages(text, entries), model=self.model, fallback=self.fallback,
+            got = self.client.chat(messages, model=self.model, fallback=self.fallback,
                                    max_tokens=self.max_tokens, temperature=0, task_run_id=task_run_id)
         except fabric_openrouter.OpenRouterError as err:
             return dict(base, action="handoff", reasons=["model:" + err.kind])
         base["costUsd"] = got["receipt"].get("costUsd")
         if got["content"].strip() == "HANDOFF":
-            return dict(base, action="handoff", reasons=["model-unsure"])
+            unsure = dict(base, action="handoff", reasons=["model-unsure"])
+            return dict(unsure, fallback=True) if repair is not None else unsure  # the repair was spent
         checked = check_reply(got["content"], text, [e["id"] for e in entries], max_chars=self.max_chars,
                               sources={e["id"]: entry_text(e) for e in entries})
         if not checked["ok"]:
-            return dict(base, action="handoff", reasons=checked["problems"], citations=checked["citations"])
-        return dict(base, action="reply", reply=checked["reply"], citations=checked["citations"], reasons=[])
+            refused = dict(base, action="handoff", reasons=checked["problems"], citations=checked["citations"],
+                           draft=got["content"])
+            return dict(refused, fallback=True) if repair is not None else refused
+        replied = dict(base, action="reply", reply=checked["reply"], citations=checked["citations"], reasons=[])
+        return dict(replied, repaired=True) if repair is not None else replied
 
 
 def from_config(config_path: Path, *, on_handoff: Optional[Callable[[Dict[str, Any]], None]] = None,
@@ -450,7 +585,13 @@ def from_config(config_path: Path, *, on_handoff: Optional[Callable[[Dict[str, A
                                       ledger=fabric_usage.JsonlUsageLedger(state / "usage.jsonl"), prices=prices,
                                       key_env=config.get("keyEnv", "OPENROUTER_API_KEY"),
                                       project_id=config.get("projectId"), **overrides)
-    return SupportAgent(knowledge=Knowledge.load(home / config["knowledge"]), client=client, model=config["model"],
+    knowledge: Union[Knowledge, KnowledgeSource]
+    if config.get("knowledgeMaxAgeSeconds") is not None:  # the file as a source with an age (FAA-197)
+        knowledge = KnowledgeSource(home / config["knowledge"], max_age_s=config["knowledgeMaxAgeSeconds"])
+        knowledge.current()  # read once, now: a bad file fails here as a RecipeError
+    else:
+        knowledge = Knowledge.load(home / config["knowledge"])
+    return SupportAgent(knowledge=knowledge, client=client, model=config["model"],
                         fallback=config["fallback"], state_dir=state, max_tokens=int(config.get("maxTokens", 600)),
                         max_chars=int(config.get("maxChars", 1200)), on_handoff=on_handoff)
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/connectors.md

@@ -45,8 +45,10 @@ const answer = await request('GET', 'https://api.example/v1/items', { headers, d
 
 Every answer comes back as a `Response`, whatever its status; `HttpError` means no usable answer came, with `kind`
 `connection`, `timeout`, `too-large` or `refused`, the status when there was one, and the URL redacted to scheme,
-host, port and path (`redact_url`); a URL that is not http or https keeps only its scheme (`htps:<redacted>`), and
-one that does not parse as a URL is `<unparseable url>`. The path is not redacted (Node writes it as `new URL`
+host, port and path (`redact_url`); a URL that is not http or https keeps only its scheme (`htps:<redacted>`, and `ssh:<redacted>`
+for `ssh://h:99999/r` too), and an http, https, ws, wss or ftp URL that does not parse (Node reads it with `new URL`;
+Python reads its own special-scheme form and prints what it finds, never the user information), or a value with no
+scheme, is `<unparseable url>`. The path is not redacted (Node writes it as `new URL`
 normalises it, Python as given), so a key never belongs in it. Python's `check_url` refuses a host
 with a backslash, space, control character (C0, DEL or C1) or `%`, a URL with a space or ASCII control character before its
 first `#` (the default transport sends a URL up to there, as Node's does; a transport you pass receives the URL as given), or a character outside ASCII in its path or query (ASCII whitespace at its ends is trimmed, as urllib and `new URL` trim it; a Unicode space ending the part before the first `#` is refused, where Node keeps it percent-encoded), a bracketed host that is not an IPv6 address with no zone, and a port that is not

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/delegation.md

@@ -133,8 +133,8 @@ part before the first `#` is refused, as `check_url` refuses it, because Node ke
 trim it and read the keys when it ends the URL); a leading space is refused as not a URL), a host holding `%`, a backslash, a Unicode space or a control character (urllib
 would decode or dial it as another host), a bracketed host that is no IPv6 address, a port that is not ASCII digits or is above
 65535, no host, and an empty userinfo. The Node kit accepts several of these as `new URL` reads them, among them a `%`
-host decoded, a backslash as `/`, a tab or line break removed, an empty userinfo dropped and an extra slash before the
-host skipped. The
+host decoded, a backslash as `/`, a tab or line break removed and an extra slash before the host skipped. A user
+information as written is refused by both kits, empty or holding a backslash (since 0.62.0). The
 Python kit verifies Ed25519 itself (RFC 8032, standard library only, strict as OpenSSL: `S` below the group order,
 canonical points, no small-order key); it follows no redirect when it reads the key set; the Node kit uses `node:crypto` and refuses small-order keys
 itself (`isSmallOrderKey`), because Node before 26 lets OpenSSL accept a signature under one.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/estate-record.md

@@ -202,6 +202,8 @@ const { dirs, instance, lock } = await holdContextInstance('example-agent', 'org
   `~/Library/Application Support/<id>.<instance>`, `~/Library/Logs/<id>.<instance>`, `~/Library/Caches/<id>.<instance>`),
   never inside the personal tree. `launchd_uninstall(..., purge=True, service_id=..., instance=...)` /
   `launchdUninstall(..., {purge, serviceId, instance})` purge only that instance's folders.
+- **Its descriptor names its repository.** A new instance is a new install, so its descriptor passes
+  `source.repository` as the personal one does (FAA-198, since 0.62.0); without it the write is refused.
 - **What it checks, before anything is created.** `context_instance` / `contextInstance` is pure and answers
   `{context, kind, org?, instance, key, dirs, descriptorPath, grant?}`, never the record. An organization's instance
   needs the estate record revision this machine applied (verified with `verify_estate_record`; the helper verifies no

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/lifecycle.md

@@ -86,7 +86,8 @@ that document until `service.id` matches (at most 40 s) before it calls the serv
 
 1. Build or unpack the release into `~/.local/share/<id>/releases/<version>-<sha12>/`
    (a venv or `node_modules` inside it). Never edit a release after it is written.
-2. `write_descriptor` (port and id claims are checked here).
+2. `write_descriptor` (port and id claims are checked here, and a new descriptor without `source.repository` is
+   refused; a rewrite of an installed one warns, FAA-198).
 3. `launchd_install` (Node: `await launchdInstall(...)`, the same steps): write + `plutil -lint`, read `launchctl print-disabled gui/<uid>`,
    `enable` **only when no override is recorded** (a first install), `bootout` and wait
    until `launchctl print gui/<uid>/<label>` fails, `bootstrap` with up to five retries,
@@ -150,7 +151,8 @@ never infers supervision from its parent process.
 
 **An app** a person installs and starts has no supervisor (contract DEC-0069). Its descriptor says
 `"lifecycle": {"manager": "person", "app": "<the installed bundle or executable>"}`, `installedBy {by: "person", role,
-tool}` and no `origin`: it says the app is installed, never that it runs. The installer writes it; where there is none
+tool}`, `source.repository` (the app's own repository; its first write is refused without it, FAA-198) and no `origin`:
+it says the app is installed, never that it runs. The installer writes it; where there is none
 (a macOS app dragged into Applications), the app writes it on a start when `app_descriptor_action` /
 `appDescriptorAction` answers `write` (no descriptor yet, another version in `installedBy.tool`, or another path than
 `lifecycle.app`), and never from an App Translocation path. Its live origin and process id go in its own liveness file,

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/migrating-a-service.md

@@ -15,10 +15,12 @@ Order matters: each step leaves the service answering.
    delete it with the operator's consent.
 6. **Regenerate the plist** from `launchd_plist`, pointing at a release; delete stray
    `.plist.bak` files from `~/Library/LaunchAgents` after moving them elsewhere.
-7. **Write the descriptor** from the installer; resolve any port claim it refuses by
-   moving the newcomer, never the established service.
-8. **Re-run the probe** until nothing `FAIL`s; record the table in the service's
-   verification document.
+7. **Write the descriptor** from the installer, with `source.repository` (a new descriptor without it is refused);
+   resolve any port claim it refuses by moving the newcomer, never the established service.
+8. **Declare what it uses** with `connections_extension` / `connectionsExtension` in the well-known document; a
+   service that uses nothing outside itself declares an empty list (`connections_extension([])`), which reads `PASS`.
+9. **Re-run the probe** until nothing `FAIL`s and `descriptor.source-repository` and `well-known.connections` read
+   `PASS` (a `NOT_RUN` is not a pass); record the table in the service's verification document.
 
 ## Gaps that existing services usually have
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/package.md

@@ -141,8 +141,8 @@ key, the partner and the organization contexts, and `placement_trust` / `placeme
 one of those contexts and to no other (FAC-SEM-122, [the estate record reference](estate-record.md)). The partner's own
 agents call the company's agents with the partner innermost in the delegation chain ([delegation](delegation.md)).
 
-Still to come, each waiting on its owner: a partner's own space in a catalog and publishing to it (FAA-44, Vesta
-PA-03).
+Still to come, each waiting on its owner: a partner's own space in a catalog and publishing to it (FAA-44, the organization
+edition's PA-03).
 
 ## What this version does not do
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/protocol.md

@@ -55,7 +55,8 @@ File `<id>.<instance>.json`, mode 0600 (on Windows a protected ACL), atomic.
 | `lifecycle` | `manager` `launchd` (then `label` and `plist`), `systemd` (then `unit`, a `systemctl --user` unit), `task-scheduler` (then `task`, a per-user Scheduled Task), `node` (Project Observatory's node supervises it as its child, with no supervisor file, DEC-0061), `person` (an app a person installs and starts, then `app`, the installed app, DEC-0069) or `none`; `unit` and `task` are refused beside any other manager (DEC-0032), `label` and `plist` beside any but `launchd` (DEC-0057), `app` beside any but `person`. Both kits and the probe accept all six; both kits write the unit and the task (`systemd_unit`, `task_xml` / `systemdUnit`, `taskXml`). An app's descriptor says it is installed, never that it runs: the probe checks `app` is still there (`descriptor.app-installed`) and reads no well-known document; a reader that finds the app gone treats the descriptor as stale (`app_descriptor_stale` / `appDescriptorStale`), and an app that writes its own descriptor rewrites it only when `app_descriptor_action` / `appDescriptorAction` says `write` |
 | `paths` | `data` (required), `logs[]`, optional `config`, `cache` |
 | `commands` | only `doctor` and `update`, argument arrays whose first item is an absolute or `~/` path (Windows: also `C:\…`, `C:/…` or `~\…`, never a network share; DEC-0032) |
-| `source.repository`, `fabricManifest` | optional |
+| `source.repository` | the repository of the service's code (`https://github.com/owner/name`), which links the agent to its project. Optional in the schema; the kit's `write_descriptor` / `writeDescriptor` refuse a new descriptor without it since 0.62.0 (`source_refusal` / `sourceRefusal` says why, FAA-198), and rewriting one already installed without it warns (`NoSourceRepositoryWarning`; Node `process.emitWarning` with code `FABRIC_NO_SOURCE_REPOSITORY`), so an installed agent's update keeps working. The probe names its absence (`descriptor.source-repository`, `NOT_RUN`) |
+| `fabricManifest` | optional |
 | `installedAt`, `installedBy` | when, and who installed it: the installer and its version as a string, or `{by, role?, tool}` (DEC-0061): `by` `person` (with `role` `operator` or `administrator`), `node` or `organization`; `role` for a person only; `tool` the installer and its version. It names a role, never a person. An app's descriptor uses the object form with `by: "person"`. `register_remote` / `registerRemote` and the sample write the object form |
 | `runner` | optional `{kind?, credentialKind}` (DEC-0061): `credentialKind` `subscription`, `key`, `platform-metered` or `none`: a kind, never a credential (`FAC-SEM-086` refuses a credential-shaped value here or in `installedBy`); a subscription names its vendor's runner (`claude-code`, `kimi-code`, `codex`) |
 | `peer` | optional `{endpoint, custody, residency, maxDataClass}` (DEC-0061): the service is offered to others. `endpoint` `https://<dns-name>[:<port>][/<path>]`, never a reserved name (`FAC-SEM-085`); `custody` `organization-managed`, `personal` or `processor-hosted` (an organization's cloud a processor runs under a processing agreement, DEC-0099); `residency` 1–32 ISO 3166-1 alpha-2 codes, `EU` admitted, user-assigned codes refused; `maxDataClass` `public` < `internal` < `confidential` < `restricted`. An offer needs `runner` and never runs on a subscription. A host sends a request from anyone but the operator only when `peer_refusal` / `peerRefusal` answers null (`FAC-SEM-088`); usage rows may take `route: "platform-metered"` |
@@ -127,7 +128,8 @@ No auth; the Host/Origin guard applies; answered from memory in under 100 ms.
   `connectionsExtension(declared, {degraded, states})`: `state` comes from the service's own checks (`states`, by
   `id`), else `degraded` when `degraded[]` names it, else `unknown`; a declaration a host would hide is refused with
   `ServiceError`, and `build_well_known` refuses one passed in by hand. `connections_view` / `connectionsView` read
-  a peer's list as Fabric Dashboards does, and `check_service.py` reports `well-known.connections`. Build it each
+  a peer's list as Fabric Dashboards does, and `check_service.py` reports `well-known.connections` (`NOT_RUN` when
+  the document has no connections declaration, FAA-199, and `PASS` for an empty list; the reference service declares its template and its demo source). Build it each
   time the well-known document is built, from the same `degraded` list:
 
   ```python

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/remote-placement.md

@@ -42,8 +42,18 @@ same objects (well-known document, events feed, login code) at the same paths.
 - `commands` may carry `doctor` (a local executable); never `update`.
 - `source.repository` names the repository of the service's code, so Fabric Dashboards can tell code apart from a store
   that versions data. Pass it as `registerRemote({ ..., source: { repository } })` / `register_remote(..., source=...)`
-  (since 0.49.3); the kit checks it as the schema's URI (RFC 3986 characters, a host and a valid port when it names an
-  authority) and refuses a `user:password@` or any value shaped like a credential in it.
+  (since 0.49.3; a new registration without it is refused since 0.62.0, before the token file is written, and a
+  rotation that passes none keeps the installed one, FAA-198); the
+  kit checks it as the schema's URI (RFC 3986 characters, a host and a valid port when it names an
+  authority) and refuses a `user:password@`, a user outside a URL's authority (an scp form), and a value shaped like a
+  credential in its user, query or fragment or as a path segment; a path segment in lower case, or of letters with no
+  digit, is the repository's name unless a key's shape starts it or follows a `.`, `_` or `-` in it (since 0.62.0, so
+  `task-pipeline-dashboard` and `Task-Pipeline-Dashboard` are accepted, a name that starts with `sk-` and 16 more
+  characters is not, in any case, nor `%73k-` and the rest; a host is read for a key's shape anywhere in it, inside a word too, so
+  `task-pipeline-dashboard.example.com` is refused, FAA-200 (32)). A path and a user information are read as written and with
+  their ASCII escapes decoded, and a password as written and as the URL standard reads it (`https://h\u:pw@x/r` is
+  refused). A checkout's origin in scp form (`git@host:owner/name.git`) is refused: write it `https://host/owner/name`,
+  the repository's own page with no path below it, no query and no fragment, which the estate's readers join.
 - `installedBy` is the installer's name and version as a string (`"example-installer 1.2.0"`), or
   `{by, role?, tool}` where `by` is `person`, `node` or `organization` and `role` (`operator`, `administrator`) is a
   person's only. There is no `agent` kind: an agent that registers a service writes the string form, or
@@ -111,5 +121,8 @@ The login rules keep every `Set-Cookie` of the answer and judge the session cook
 
 Rotate the token by setting the new value on the platform and re-running `registerRemote` on the
 operator's computer with it; the old token stops working the moment the platform restarts with the
-new value, and so does every session begun under it when `LoginCodes` has `token=`. Rotate the
+new value, and so does every session begun under it when `LoginCodes` has `token=`. The re-run keeps the
+installed `source` when it passes none (one the kit refuses, edited by hand, is dropped with the warning); pass
+`runner`, `peer`, `summary`, `doctor` and `installedBy` / `installed_by` again, since a re-run writes only what it is
+given (without `installedBy` it writes the default person form). Rotate the
 session key on the platform to sign every operator out.

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

@@ -64,6 +64,7 @@ from typing import Any, Dict, List, Optional, Tuple
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 import fabric_service as fs  # noqa: E402
 import fabric_connections as fcn  # noqa: E402
+from check_service_rules import shown_repository  # noqa: E402 - a repository in evidence carries no userinfo or query
 import fabric_interop as fi  # noqa: E402
 
 Result = Dict[str, str]
@@ -194,6 +195,18 @@ class Probe:
         else:
             unique = "port %d is unique" % self.port
         self.add("descriptor.port-claim", "FAIL" if clashes else "PASS", "; ".join(clashes) or unique)
+        # FAA-198: the repository that links the agent to its project; a new install is refused without it, an installed one
+        # is named here (NOT_RUN is no pass) until its owner adds it.
+        # A source descriptor.valid refuses is no pass either, and the evidence never carries a URL's userinfo or query,
+        # where a password rides (0.62.0 unit reading 2).
+        if not fs.names_repository(self.d):
+            self.add("descriptor.source-repository", "NOT_RUN", "the descriptor %s" % fs.NO_SOURCE_REPOSITORY)
+        # what the source adds, read in the member rules, which a missing required key never cuts short (unit reading 16)
+        elif added := sorted(set(fs.descriptor_member_problems(self.d)) - set(fs.descriptor_member_problems(
+                {k: v for k, v in self.d.items() if k != "source"}))):  # its own problem (a member name it names is the descriptor's own, FAA-200 (39))
+            self.add("descriptor.source-repository", "NOT_RUN", "source is refused: %s" % added[0])
+        else:
+            self.add("descriptor.source-repository", "PASS", "names %s" % shown_repository(self.d["source"]["repository"]))
         if (self.d.get("lifecycle") or {}).get("manager") == "person":
             # DEC-0069: installed, never running — a reader checks the app is still there; liveness is the app's own file.
             present = fs.app_present(self.d)
@@ -275,6 +288,9 @@ class Probe:
             self.add("well-known.connections", "FAIL" if view["reported"] else "PASS",
                      "; ".join(f["message"] for f in fcn.connections_rules(wk)[:5]) or
                      "%d connection(s), %d named in degraded[]" % (len(view["connections"]), failing))
+        else:  # FAA-199: named, never a pass, so the connection map is not left empty unseen
+            self.add("well-known.connections", "NOT_RUN", "declares no %s: a host cannot draw what the service uses "
+                     "(connections_extension / connectionsExtension)" % fcn.CONNECTIONS_EXTENSION_KEY)
         # DEC-0121, FAC-SEM-142: every button's agent twin, declared; no declaration is NOT_RUN (D10).
         self.add("well-known.actions", *well_known_actions_verdict(wk))
         # DEC-0122: where the public Agent Card is; no member is NOT_RUN.
@@ -809,9 +825,9 @@ class Probe:
         if not source:
             self.add(rule, "NOT_RUN", "data is inside repository %s and the descriptor names no source.repository to tell code from data" % top)
         elif remote.returncode == 0 and same_repository(remote.stdout.strip(), source):
-            self.add(rule, "FAIL", "data lives in the service's own code checkout %s (%s)" % (top, source))
+            self.add(rule, "FAIL", "data lives in the service's own code checkout %s (%s)" % (top, shown_repository(source)))
         else:
-            self.add(rule, "PASS", "data is in repository %s, which is not the service's code (%s)" % (top, remote.stdout.strip() or "no remote"))
+            self.add(rule, "PASS", "data is in repository %s, which is not the service's code (%s)" % (top, shown_repository(remote.stdout.strip()) or "no remote"))
 
     def lock_rule(self, data: Path) -> None:
         lock = data / "service.lock"