@passioncode-ai/fabric-agent-adapter 0.23.0 → 0.25.0

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

@@ -0,0 +1,182 @@
+"""Identifier equality (contract DEC-0076): two identifiers are the same when their normal forms are equal.
+
+A port of the contract's `src/identifiers.ts`, held to its `fixtures/vectors/identifiers.json`. The normal form of a URI
+is RFC 3986 §6.2.2 syntax-based normalization: the scheme and the host lower-cased and percent-encoding hex upper-cased
+(§6.2.2.1), percent-encoded unreserved characters decoded (§6.2.2.2), dot segments removed from a hierarchical path
+(§6.2.2.3), and only the leading ones from a rootless path; nothing scheme-based (§6.2.3). A `urn:` URI follows RFC 8141
+§3.1 instead: the scheme and the NID lower-cased, percent-encoding hex upper-cased, nothing decoded, the NSS's case kept,
+the r-, q- and f-components ignored. A string that is not a URI by RFC 3986's `URI` production is its own normal form.
+Nothing here raises. Standard library only; this file is byte-identical in both skills' `scripts/`."""
+from __future__ import annotations
+
+import re
+from typing import Any, Optional, Tuple
+
+_UNRESERVED = r"A-Za-z0-9\-._~"
+_SUB_DELIMS = r"!$&'()*+,;="
+_PCT = r"%[0-9A-Fa-f]{2}"
+
+
+def _run(chars: str) -> "re.Pattern[str]":
+    """`*( <chars> / pct-encoded )`, linear: one character class beside one fixed triplet."""
+    return re.compile(r"(?:[%s]|%s)*" % (chars, _PCT), re.ASCII)
+
+
+_USERINFO = _run(_UNRESERVED + _SUB_DELIMS + ":")
+_REG_NAME = _run(_UNRESERVED + _SUB_DELIMS)
+_PATH = _run(_UNRESERVED + _SUB_DELIMS + ":@/")
+_QUERY = _run(_UNRESERVED + _SUB_DELIMS + ":@/?")
+_PORT = re.compile(r"[0-9]*", re.ASCII)
+_SCHEME = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*", re.ASCII)
+
+# RFC 3986 §3.2.2: IP-literal = "[" ( IPv6address / IPvFuture ) "]".
+_H16 = "[0-9A-Fa-f]{1,4}"
+_DEC_OCTET = "(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])"
+_IPV4 = r"%s(?:\.%s){3}" % (_DEC_OCTET, _DEC_OCTET)
+_LS32 = "(?:%s:%s|%s)" % (_H16, _H16, _IPV4)
+_IPV6 = "|".join([
+    "(?:%s:){6}%s" % (_H16, _LS32),
+    "::(?:%s:){5}%s" % (_H16, _LS32),
+    "(?:%s)?::(?:%s:){4}%s" % (_H16, _H16, _LS32),
+    "(?:(?:%s:){0,1}%s)?::(?:%s:){3}%s" % (_H16, _H16, _H16, _LS32),
+    "(?:(?:%s:){0,2}%s)?::(?:%s:){2}%s" % (_H16, _H16, _H16, _LS32),
+    "(?:(?:%s:){0,3}%s)?::%s:%s" % (_H16, _H16, _H16, _LS32),
+    "(?:(?:%s:){0,4}%s)?::%s" % (_H16, _H16, _LS32),
+    "(?:(?:%s:){0,5}%s)?::%s" % (_H16, _H16, _H16),
+    "(?:(?:%s:){0,6}%s)?::" % (_H16, _H16),
+])
+_IP_LITERAL = re.compile(r"\[(?:%s|[Vv][0-9A-Fa-f]+\.[%s%s:]+)\]" % (_IPV6, _UNRESERVED, _SUB_DELIMS), re.ASCII)
+
+# RFC 8141 §2: NID = (alphanum) 0*30(ldh) (alphanum), then ":" and a non-empty NSS.
+_URN_NAME = re.compile(r"([A-Za-z0-9][A-Za-z0-9-]{0,30}[A-Za-z0-9]):(.+)", re.ASCII | re.DOTALL)
+_SPLIT = re.compile(r"([^:/?#]+):(?://([^/?#]*))?([^?#]*)(?:\?([^#]*))?(?:#(.*))?", re.DOTALL)
+_TRIPLET = re.compile(r"%([0-9A-Fa-f]{2})")
+_UNRESERVED_CHAR = re.compile(r"[A-Za-z0-9\-._~]", re.ASCII)
+
+
+def _percent(text: str, keep_encoded: bool = False) -> str:
+    """Percent-encoding hex upper-cased (§6.2.2.1), and unreserved characters decoded unless ``keep_encoded``."""
+    def one(match: "re.Match[str]") -> str:
+        char = chr(int(match.group(1), 16))
+        return char if not keep_encoded and _UNRESERVED_CHAR.fullmatch(char) else "%" + match.group(1).upper()
+    return _TRIPLET.sub(one, text)
+
+
+def _strip_leading_dots(path: str) -> str:
+    """A rootless path loses its leading "./" and "../" segments while what is left stays rootless (DEC-0076)."""
+    start = 0
+    while path.startswith("./", start) or path.startswith("../", start):
+        start += 2 if path.startswith("./", start) else 3
+    rest = path[start:]
+    return path if rest == "" or rest.startswith("/") else rest
+
+
+def _remove_dot_segments(path: str) -> str:
+    """RFC 3986 §5.2.4 remove_dot_segments over a path whose "." and ".." are already decoded."""
+    absolute = path.startswith("/")
+    segments = (path[1:] if absolute else path).split("/")
+    output = []
+    for index, segment in enumerate(segments):
+        last = index == len(segments) - 1
+        if segment in (".", ".."):
+            if segment == ".." and output:
+                output.pop()
+            if last:  # a dot segment that ends the path leaves it ending in "/"
+                output.append("")
+            continue
+        output.append(segment)
+    return ("/" if absolute else "") + "/".join(output)
+
+
+def _authority_parts(authority: str) -> Optional[Tuple[Optional[str], str, Optional[str]]]:
+    at = authority.rfind("@")
+    userinfo = None if at == -1 else authority[:at]
+    host_port = authority if at == -1 else authority[at + 1:]
+    bracket = host_port.find("]") if host_port.startswith("[") else -1
+    colon = host_port.find(":", 0 if bracket == -1 else bracket)
+    host = host_port if colon == -1 else host_port[:colon]
+    port = None if colon == -1 else host_port[colon + 1:]
+    if userinfo is not None and not _USERINFO.fullmatch(userinfo):
+        return None
+    if port is not None and not _PORT.fullmatch(port):
+        return None
+    if not (_IP_LITERAL.fullmatch(host) if host.startswith("[") else _REG_NAME.fullmatch(host)):
+        return None
+    return userinfo, host, port
+
+
+def _parse(text: str) -> Optional[Tuple[str, Optional[str], str, Optional[str], Optional[str]]]:
+    """RFC 3986 Appendix B's split, then each component checked against its §3 production; None when one fails."""
+    match = _SPLIT.fullmatch(text)
+    if not match:
+        return None
+    scheme, authority, path, query, fragment = match.groups()
+    path = path or ""
+    if not _SCHEME.fullmatch(scheme) or not _PATH.fullmatch(path):
+        return None
+    if query is not None and not _QUERY.fullmatch(query):
+        return None
+    if fragment is not None and not _QUERY.fullmatch(fragment):
+        return None
+    if authority is not None and _authority_parts(authority) is None:
+        return None
+    if authority is None and path == "":
+        return None
+    return scheme, authority, path, query, fragment
+
+
+def _urn_form(authority: Optional[str], path: str, query: Optional[str]) -> str:
+    name = _URN_NAME.fullmatch(path)
+    path = "%s:%s" % (name.group(1).lower(), _percent(name.group(2), True)) if name else _percent(path, True)
+    # A "?" not followed by "+" or "=" is no URN component (RFC 8141 §2): it is kept, never dropped unread.
+    kept = "?" + _percent(query, True) if query is not None and not re.match(r"[+=]", query) else ""
+    auth = "//" + _percent(authority, True) if authority is not None else ""
+    return "urn:%s%s%s" % (auth, path, kept)
+
+
+def _generic_form(scheme: str, authority: Optional[str], path: str, query: Optional[str], fragment: Optional[str]) -> str:
+    auth = ""
+    if authority is not None:
+        userinfo, host, port = _authority_parts(authority)  # type: ignore[misc]
+        # The host is case-insensitive (§3.2.2); its remaining percent triplets keep upper-case hex.
+        lowered = re.sub(r"%[0-9a-f]{2}", lambda m: m.group(0).upper(), _percent(host).lower())
+        auth = "//%s%s%s" % ("" if userinfo is None else _percent(userinfo) + "@", lowered, "" if port is None else ":" + port)
+    decoded = _percent(path)
+    hierarchical = authority is not None or decoded.startswith("/")
+    out = _remove_dot_segments(decoded) if hierarchical else _strip_leading_dots(decoded)
+    if authority is None and out.startswith("//"):  # it would read as an authority: keep the decoded path
+        out = decoded
+    q = "" if query is None else "?" + _percent(query)
+    f = "" if fragment is None else "#" + _percent(fragment)
+    return "%s:%s%s%s%s" % (scheme.lower(), auth, out, q, f)
+
+
+def normal_identifier(value: Any) -> Optional[str]:
+    """The normal form of an identifier: a URI's syntax-normalized form (RFC 3986 §6.2.2; RFC 8141 §3.1 for `urn:`),
+    any other string as it is, None for a value that is not a string. The contract's `normalIdentifier`."""
+    if not isinstance(value, str):
+        return None
+    parts = _parse(value)
+    if parts is None:
+        return value
+    scheme, authority, path, query, fragment = parts
+    return _urn_form(authority, path, query) if scheme.lower() == "urn" else _generic_form(scheme, authority, path, query, fragment)
+
+
+def _strict_equal(a: Any, b: Any) -> bool:
+    """JavaScript's === on parsed JSON: numbers by value, booleans only with booleans, objects by identity."""
+    if isinstance(a, bool) or isinstance(b, bool):
+        return isinstance(a, bool) and isinstance(b, bool) and a == b
+    if isinstance(a, (int, float)) and isinstance(b, (int, float)):
+        return a == b
+    if isinstance(a, (dict, list)) or isinstance(b, (dict, list)):
+        return a is b
+    return type(a) is type(b) and a == b
+
+
+def same_identifier(a: Any, b: Any) -> bool:
+    """Two identifiers are the same when their normal forms are equal (DEC-0076). A value that is not a string is no
+    identifier and is compared as it is (JavaScript's ===). The contract's `sameIdentifier`."""
+    if not isinstance(a, str) or not isinstance(b, str):
+        return _strict_equal(a, b)
+    return normal_identifier(a) == normal_identifier(b)

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

@@ -19,6 +19,7 @@ import shutil
 import subprocess
 from typing import Any, Callable, Dict, List, Optional, Sequence
 
+import fabric_identifiers as _ids
 import fabric_secrets as _secrets
 import fabric_service as _fs
 
@@ -314,9 +315,12 @@ def _object_at(value: Any, key: str) -> Dict[str, Any]:
 
 
 def _ref_key(ref: Any) -> str:
+    """A revision reference compared whole: id, revision and content hash. The id is an identifier, so it enters the key
+    in its normal form (DEC-0076)."""
     if not isinstance(ref, dict):
         return ""
-    return "%s@%s#%s" % (_field(ref, "id"), _field(ref, "revision"), _field(ref, "contentHash"))
+    normal = _ids.normal_identifier(ref.get("id"))
+    return "%s@%s#%s" % (normal if normal is not None else _field(ref, "id"), _field(ref, "revision"), _field(ref, "contentHash"))
 
 
 def _same_ref(a: Any, b: Any) -> bool:
@@ -343,7 +347,7 @@ def _runner_route(value: Dict[str, Any]) -> List[Dict[str, str]]:
 def _route_bundle(value: Dict[str, Any]) -> List[Dict[str, str]]:
     route = _object_at(value, "route")
     admitted = {_ref_key(a.get("provider")) for a in _list(value.get("admissions"))
-                if a.get("state") == "admitted" and a.get("capability", _MISSING) == route.get("capability", _MISSING)}
+                if a.get("state") == "admitted" and _ids.same_identifier(a.get("capability", _MISSING), route.get("capability", _MISSING))}
     findings = []
     for index, candidate in enumerate(_candidates(route)):
         key = _ref_key(candidate.get("provider"))
@@ -363,9 +367,10 @@ def _binding_agreement(binding: Dict[str, Any], route: Dict[str, Any]) -> List[D
     def disagree(path: str, message: str) -> None:
         findings.append(_finding("FAC-SEM-032", "/binding/" + path, message))
 
-    if binding.get("project", _MISSING) != route.get("project", _MISSING):
+    # DEC-0076: project and capability are identifiers, compared by normal form.
+    if not _ids.same_identifier(binding.get("project", _MISSING), route.get("project", _MISSING)):
         disagree("project", "the binding is for %s, the route for %s" % (_field(binding, "project"), _field(route, "project")))
-    if binding.get("capability", _MISSING) != route.get("capability", _MISSING):
+    if not _ids.same_identifier(binding.get("capability", _MISSING), route.get("capability", _MISSING)):
         disagree("capability", "the binding binds %s, the route orders %s" % (_field(binding, "capability"), _field(route, "capability")))
     if binding.get("profileKind") != "local-runner":
         disagree("profileKind", "a runner route serves the local-runner profile, not %s" % _field(binding, "profileKind"))
@@ -408,9 +413,9 @@ def _route_event(value: Dict[str, Any]) -> List[Dict[str, str]]:
 
     if not _same_ref(event.get("route"), route.get("meta")):
         wrong("/route", "the event names route %s, not %s" % (_ref_key(event.get("route")), _ref_key(route.get("meta"))))
-    if event.get("project", _MISSING) != route.get("project", _MISSING):
+    if not _ids.same_identifier(event.get("project", _MISSING), route.get("project", _MISSING)):
         wrong("/project", "the event is for %s, the route for %s" % (_field(event, "project"), _field(route, "project")))
-    if event.get("capability", _MISSING) != route.get("capability", _MISSING):
+    if not _ids.same_identifier(event.get("capability", _MISSING), route.get("capability", _MISSING)):
         wrong("/capability", "the event names %s, the route orders %s" % (_field(event, "capability"), _field(route, "capability")))
 
     def candidate_at(ref: Dict[str, Any], path: str) -> Optional[Dict[str, Any]]:

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

@@ -90,7 +90,11 @@ _SPAN_ID = re.compile(r"^(?!0{16}$)[0-9a-f]{16}$")
 # DEC-0057: `//server/…` and `/\\server…` are shares on Windows too, so a leading slash is followed by neither.
 _LOCAL_PATH = re.compile(r"^(~[\\/]|/(?![\\/])|[A-Za-z]:[\\/])")
 # DEC-0032: the supervisor per system and the field that names its job.
-MANAGERS = ("launchd", "systemd", "task-scheduler", "none")
+# DEC-0061: `node` (Project Observatory's node supervises its children, no supervisor file); DEC-0069: `person` (an app
+# a person installs and starts; its descriptor says it is installed, never that it runs).
+MANAGERS = ("launchd", "systemd", "task-scheduler", "node", "person", "none")
+#: Managers that write no launchd label or plist (DEC-0057, DEC-0061, DEC-0069).
+_NOT_LAUNCHD = ("systemd", "task-scheduler", "node", "person")
 _AUTH_HEADER = re.compile(r"[A-Za-z][A-Za-z0-9-]{0,63}")
 _UNIT = re.compile(r"^[A-Za-z0-9][A-Za-z0-9:_.@-]{0,250}\.service$")
 _TASK = re.compile(r"^\\[A-Za-z0-9 ._\\-]{1,254}$")
@@ -886,7 +890,10 @@ def validate_descriptor(descriptor: Dict[str, Any]) -> List[str]:
     remote = placement_of(descriptor) == "remote"
     if "placement" in descriptor and descriptor["placement"] not in PLACEMENTS:
         problems.append("placement must be local or remote")
-    required = ("protocol", "id", "instance", "name", "origin", "auth", "lifecycle", "installedAt", "installedBy")
+    life_in = descriptor.get("lifecycle") if isinstance(descriptor.get("lifecycle"), dict) else {}
+    app = life_in.get("manager") == "person"
+    # DEC-0069: an app's descriptor says it is installed, never that it runs; its live origin is in its own liveness file.
+    required = ("protocol", "id", "instance", "name", "auth", "lifecycle", "installedAt", "installedBy") + (() if app else ("origin",))
     if not remote:
         required = required + ("paths",)
     for key in required:
@@ -902,7 +909,7 @@ def validate_descriptor(descriptor: Dict[str, Any]) -> List[str]:
         problems.append("instance must match %s" % _INSTANCE.pattern)
     if remote:
         problems.extend(remote_origin_problems(descriptor["origin"]))
-    elif not _ORIGIN.match(str(descriptor["origin"])):
+    elif "origin" in descriptor and not _ORIGIN.match(str(descriptor["origin"])):
         problems.append("origin must be http://127.0.0.1:<port>")
     auth = descriptor.get("auth") or {}
     if "tokenFile" not in auth:
@@ -924,14 +931,21 @@ def validate_descriptor(descriptor: Dict[str, Any]) -> List[str]:
     life = descriptor.get("lifecycle") or {}
     manager = life.get("manager")
     if manager not in MANAGERS:
-        problems.append("lifecycle.manager must be launchd, systemd, task-scheduler or none")
+        problems.append("lifecycle.manager must be launchd, systemd, task-scheduler, node, person or none")
+    # DEC-0069: `app` is the installed app of a person's descriptor, and nothing else's.
+    if manager == "person" and "app" not in life:
+        problems.append("a person's app declares lifecycle.app, the installed app")
+    if "app" in life and manager != "person":
+        problems.append("lifecycle.app belongs to manager person only")
+    if "app" in life and not _LOCAL_PATH.match(str(life["app"])):
+        problems.append("lifecycle.app must be a local path")
     if manager == "launchd" and not (life.get("label") and str(life.get("plist", "")).endswith(".plist")):
         problems.append("a launchd service declares label and plist")
     if "plist" in life and not _LOCAL_PATH.match(str(life["plist"])):
         problems.append("lifecycle.plist must be a local path")
-    # DEC-0057: a descriptor names one supervisor; launchd's label and plist never sit beside another.
+    # DEC-0057, DEC-0061, DEC-0069: a descriptor names one supervisor; launchd's label and plist never sit beside another.
     for field in ("label", "plist"):
-        if field in life and manager in ("systemd", "task-scheduler"):
+        if field in life and manager in _NOT_LAUNCHD:
             problems.append("lifecycle.%s belongs to launchd, not to %s" % (field, manager))
     # DEC-0032: `unit` goes with systemd and `task` with Task Scheduler, and with nothing else.
     for field, owner, pattern in (("unit", "systemd", _UNIT), ("task", "task-scheduler", _TASK)):
@@ -949,6 +963,7 @@ def validate_descriptor(descriptor: Dict[str, Any]) -> List[str]:
                 problems.append("a remote service has no %s %s" % (of, field))
         if "update" in (descriptor.get("commands") or {}):
             problems.append("a remote service declares no update command")
+    problems.extend(descriptor_member_problems(descriptor))
     for name, argv in (descriptor.get("commands") or {}).items():
         if name not in ("doctor", "update"):
             problems.append("unknown command %s" % name)
@@ -959,6 +974,166 @@ def validate_descriptor(descriptor: Dict[str, Any]) -> List[str]:
     return problems
 
 
+# --- DEC-0061 and DEC-0069: who installed it, how its model calls sign in, offered to others, an app's own descriptor ---
+
+#: The organization edition's data classes, least sensitive first (DEC-0061, DEC-0053).
+PEER_DATA_CLASSES = ("public", "internal", "confidential", "restricted")
+#: The kind of a runner's sign-in, never a credential's value (DEC-0061).
+CREDENTIAL_KINDS = ("subscription", "key", "platform-metered", "none")
+#: A subscription runs only in its vendor's runner (DEC-0046): runner kind → login.
+SUBSCRIPTION_RUNNERS = {"claude-code": "claude", "kimi-code": "kimi", "codex": "chatgpt"}
+_PEER_ENDPOINT = re.compile(r"^https://(?P<host>([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63})(:([1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?(/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*)?$", re.ASCII)
+_RESIDENCY = re.compile(r"^(A[B-Z]|[B-PR-WY][A-Z]|Q[A-L]|Z[A-Y])$", re.ASCII)
+_RUNNER_KIND_NAME = re.compile(r"^[a-z][a-z0-9-]{1,62}$", re.ASCII)
+
+
+def _pointer(name: str) -> str:
+    """A JSON Pointer token (RFC 6901 §4)."""
+    return str(name).replace("~", "~0").replace("/", "~1")
+
+
+def _text(value: Any, low: int = 1, high: int = 200) -> bool:
+    return isinstance(value, str) and low <= len(value) <= high
+
+
+def descriptor_member_problems(descriptor: Dict[str, Any]) -> List[str]:
+    """DEC-0061 and DEC-0069 on a descriptor's `installedBy`, `runner` and `peer`, as the schema shapes them, with
+    FAC-SEM-085 (a peer on a reserved name) and FAC-SEM-086 (a credential-shaped value in `runner` or `installedBy`,
+    named by its place, never its value)."""
+    import fabric_secrets  # noqa: E402 - beside this file; the contract's detector (DEC-0044)
+    problems: List[str] = []
+    life = descriptor.get("lifecycle") if isinstance(descriptor.get("lifecycle"), dict) else {}
+    by = descriptor.get("installedBy")
+    places: List[Tuple[str, Any]] = []
+    if isinstance(by, str):
+        if not _text(by):
+            problems.append("installedBy is the installer and its version, 1 to 200 characters")
+        places.append(("/installedBy", by))
+    elif isinstance(by, dict):
+        problems += ["installedBy has no member %s" % k for k in by if k not in ("by", "role", "tool")]
+        if by.get("by") not in ("person", "node", "organization"):
+            problems.append("installedBy.by is person, node or organization")
+        if by.get("by") == "person" and by.get("role") not in ("operator", "administrator"):
+            problems.append("installedBy.role is operator or administrator for a person")
+        if by.get("by") != "person" and "role" in by:
+            problems.append("installedBy.role belongs to a person only")
+        if not _text(by.get("tool")):
+            problems.append("installedBy.tool is the installer and its version, 1 to 200 characters")
+        places += [("/installedBy/%s" % _pointer(k), v) for k, v in by.items()]
+    else:
+        problems.append("installedBy is the installer's name or {by, role?, tool}")
+    if life.get("manager") == "person" and not (isinstance(by, dict) and by.get("by") == "person"):
+        problems.append("an app's descriptor names who installed it as a person: installedBy {by: person, role, tool} (DEC-0069)")
+    runner = descriptor.get("runner")
+    if "runner" in descriptor:
+        if not isinstance(runner, dict):
+            problems.append("runner is {kind?, credentialKind}")
+            runner = {}
+        problems += ["runner has no member %s" % k for k in runner if k not in ("kind", "credentialKind")]
+        if runner.get("credentialKind") not in CREDENTIAL_KINDS:
+            problems.append("runner.credentialKind is subscription, key, platform-metered or none")
+        if "kind" in runner and not (isinstance(runner["kind"], str) and _RUNNER_KIND_NAME.match(runner["kind"])):
+            problems.append("runner.kind is a runner kind's name")
+        if runner.get("credentialKind") == "subscription" and runner.get("kind") not in SUBSCRIPTION_RUNNERS:
+            problems.append("a subscription runs only in its vendor's runner: runner.kind claude-code, kimi-code or codex")
+        places += [("/runner/%s" % _pointer(k), v) for k, v in runner.items()]
+    if "peer" in descriptor:
+        peer = descriptor.get("peer")
+        if not isinstance(peer, dict):
+            problems.append("peer is {endpoint, custody, residency, maxDataClass}")
+            peer = {}
+        problems += ["peer has no member %s" % k for k in peer if k not in ("endpoint", "custody", "residency", "maxDataClass")]
+        endpoint = peer.get("endpoint")
+        match = _PEER_ENDPOINT.match(endpoint) if isinstance(endpoint, str) and len(endpoint) <= 2048 else None
+        if not match:
+            problems.append("peer.endpoint is https://<dns-name>[:<port>][/<path>], no query, fragment, userinfo or IP literal")
+        elif _RESERVED_HOST.search(match.group("host")):
+            problems.append("FAC-SEM-085: a service offered to others cannot be reached at the reserved name %s" % match.group("host"))
+        if peer.get("custody") not in ("organization-managed", "personal"):
+            problems.append("peer.custody is organization-managed or personal")
+        residency = peer.get("residency")
+        if (not isinstance(residency, list) or not 1 <= len(residency) <= 32 or len(set(map(json.dumps, residency))) != len(residency)
+                or not all(isinstance(r, str) and _RESIDENCY.match(r) for r in residency)):
+            problems.append("peer.residency is 1 to 32 distinct ISO 3166-1 alpha-2 codes in upper case, EU admitted, no user-assigned code")
+        if peer.get("maxDataClass") not in PEER_DATA_CLASSES:
+            problems.append("peer.maxDataClass is public, internal, confidential or restricted")
+        if "runner" not in descriptor:
+            problems.append("a service offered to others declares runner (DEC-0061)")
+        elif isinstance(runner, dict) and runner.get("credentialKind") == "subscription":
+            problems.append("a service offered to others never runs on a subscription (DEC-0061)")
+    for place, value in places:
+        if isinstance(value, str) and fabric_secrets.secret_argument(value):
+            problems.append("FAC-SEM-086: %s holds a value shaped like a credential; it names a kind, a role or an installer" % place)
+    return problems
+
+
+def peer_refusal(descriptor: Any, data_class: Any) -> Optional[str]:
+    """The host's check before it routes a request from anyone but the service's operator (DEC-0061, FAC-SEM-088):
+    `not-offered` (no `peer`), `peer-invalid` (its maximum is not one of the four classes), `data-class-unknown` (the
+    request's class is not one of them, exactly as written) or `above-max-data-class`; None when it may. The contract's
+    `peerRefusal`."""
+    if not isinstance(descriptor, dict) or not isinstance(descriptor.get("peer"), dict):
+        return "not-offered"
+    ceiling = descriptor["peer"].get("maxDataClass")
+    if not isinstance(ceiling, str) or ceiling not in PEER_DATA_CLASSES:
+        return "peer-invalid"
+    if not isinstance(data_class, str) or data_class not in PEER_DATA_CLASSES:
+        return "data-class-unknown"
+    return "above-max-data-class" if PEER_DATA_CLASSES.index(data_class) > PEER_DATA_CLASSES.index(ceiling) else None
+
+
+def app_descriptor_action(existing: Any, tool: str, app_path: str) -> str:
+    """What an app that writes its own descriptor does with it on a start (DEC-0069): `keep` when it runs from a
+    translocated copy (macOS App Translocation); otherwise `write` when there is none, when it is not an app's descriptor,
+    when its version (`installedBy.tool`) or its path (`lifecycle.app`) differs; `keep` otherwise. The contract's
+    `appDescriptorAction`."""
+    if "/AppTranslocation/" in app_path:
+        return "keep"
+    if not isinstance(existing, dict) or not isinstance(existing.get("installedBy"), dict):
+        return "write"
+    recorded = existing["lifecycle"].get("app", _MISSING_APP) if isinstance(existing.get("lifecycle"), dict) else _MISSING_APP
+    return "keep" if existing["installedBy"].get("tool", _MISSING_APP) == tool and recorded == app_path else "write"
+
+
+_MISSING_APP = object()
+
+
+def app_descriptor_stale(descriptor: Any, app_present: bool) -> bool:
+    """Whether a reader treats a descriptor as stale (DEC-0069): an app's descriptor whose installed app it did not find.
+    A supervised service's descriptor is never stale by this test. The contract's `appDescriptorStale`."""
+    life = descriptor.get("lifecycle") if isinstance(descriptor, dict) else None
+    return isinstance(life, dict) and life.get("manager") == "person" and not app_present
+
+
+def app_present(descriptor: Dict[str, Any]) -> bool:
+    """Whether `lifecycle.app` of an app's descriptor exists on this machine (a bundle is a folder, an executable a file)."""
+    life = descriptor.get("lifecycle") if isinstance(descriptor.get("lifecycle"), dict) else {}
+    app = life.get("app")
+    try:
+        return isinstance(app, str) and expand(app).exists()
+    except ServiceError:  # not a local path: nothing installed there
+        return False
+
+
+#: Fabric's own descriptor (Fabric ADR-0139): `services/fabric.default.json`.
+FABRIC_SERVICE = ("fabric", "default")
+
+
+def fabric_button_presence(directory: Optional[Path] = None) -> str:
+    """`present` or `absent` for Fabric's button (DEC-0040 FB-5, DEC-0069, Fabric SCN-142): present when Fabric's own
+    descriptor is registered and, for an app's descriptor, its app is still installed. A server sets
+    `data-fabric="absent"` on the button's script otherwise. The button only follows a link, so the liveness file is
+    not read here; a caller that sends anything reads it."""
+    path = descriptor_path(*FABRIC_SERVICE, directory=directory)
+    try:
+        found = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return "absent"
+    if not isinstance(found, dict) or validate_descriptor(found):
+        return "absent"
+    return "absent" if app_descriptor_stale(found, app_present(found)) else "present"
+
+
 def placement_of(descriptor: Dict[str, Any]) -> str:
     """DEC-0019: ``local`` unless the descriptor says ``remote``."""
     return "remote" if (descriptor or {}).get("placement") == "remote" else "local"
@@ -990,11 +1165,11 @@ def write_descriptor(descriptor: Dict[str, Any], directory: Optional[Path] = Non
         raise ServiceError("Descriptor is invalid: %s." % "; ".join(problems))
     root = directory or services_dir()
     me = "%s.%s" % (descriptor["id"], descriptor["instance"])
-    # DEC-0019: only a local placement claims a port on this computer.
-    port = None if placement_of(descriptor) == "remote" else port_of(descriptor["origin"])
+    # DEC-0019: only a local placement claims a port on this computer; DEC-0069: an app's descriptor names none.
+    port = None if placement_of(descriptor) == "remote" or "origin" not in descriptor else port_of(descriptor["origin"])
     for path, other in read_descriptors(root):
         key = "%s.%s" % (other.get("id"), other.get("instance", "default"))
-        if key == me or port is None:  # a remote origin's port is another computer's
+        if key == me or port is None:  # a remote origin's port is another computer's; an app claims none
             continue
         try:
             other_port = port_of(str(other.get("origin", "")))
@@ -1096,6 +1271,8 @@ _PROFILE_ID = re.compile(r"^[a-z][a-z0-9-]{0,62}$")
 _RUNNER_KIND = re.compile(r"^[a-z][a-z0-9-]{1,62}$")
 _MODEL_ID = re.compile(r"^[a-z0-9][a-z0-9._-]{0,63}/[a-z0-9][a-z0-9._:-]{0,127}$")
 ROUTES = ("subscription", "key")
+#: A usage row's route (DEC-0046, DEC-0061): beside a configuration's two, the hosting platform's own metered models.
+USAGE_ROUTES = ROUTES + ("platform-metered",)
 
 
 def configuration_problems(doc: Any) -> List[str]:
@@ -1289,12 +1466,12 @@ def make_usage_receipt(provider: str, model: str, *, input_tokens: int, output_t
     basis = cost_basis or ("unknown" if cost_usd is None else "provider")
     if basis not in COST_BASES or (cost_usd is None) != (basis == "unknown"):
         raise ServiceError("cost_basis is provider or price-list with a cost, unknown without one.")
-    if route is not None and route not in ROUTES:
-        raise ServiceError("route is subscription or key (DEC-0046).")
+    if route is not None and route not in USAGE_ROUTES:
+        raise ServiceError("route is subscription, key or platform-metered (DEC-0046, DEC-0061).")
     receipt = {"at": at or now_iso(), "provider": provider, "model": model, **counts,
                "costUsd": None if cost_usd is None else float(cost_usd), "costBasis": basis}
     if route is not None:
-        receipt["route"] = route  # the operator's own login in its vendor's runner, or an issued key
+        receipt["route"] = route  # the operator's own login in its vendor's runner, an issued key, or the platform's metered models
     return receipt
 
 
@@ -2346,18 +2523,30 @@ def remote_token_file(service_id: str, instance: str = "default", directory: Opt
 
 def register_remote(*, service_id: str, name: str, origin: str, token: str, instance: str = "default",
                     summary: Optional[str] = None, doctor: Optional[List[str]] = None,
-                    directory: Optional[Path] = None, installed_by: str = "fabric-service register-remote") -> Path:
+                    directory: Optional[Path] = None, installed_by: Any = None,
+                    runner: Optional[Dict[str, str]] = None, peer: Optional[Dict[str, Any]] = None) -> Path:
     """DEC-0019, installer side: register an online service on THIS computer — the token file
-    (0600, never printed) and the descriptor. The same token is set on the platform as a secret."""
+    (0600, never printed) and the descriptor. The same token is set on the platform as a secret.
+
+    DEC-0061: ``installed_by`` defaults to ``{"by": "person", "role": "operator", "tool": "fabric-service
+    register-remote"}`` (a person runs this); pass ``role: "administrator"`` for an organization's administrator, or a
+    string as before. ``runner`` (``{kind?, credentialKind}``) says how its model calls sign in, as a kind and never a
+    credential; ``peer`` (``{endpoint, custody, residency, maxDataClass}``) offers it to others and needs ``runner``."""
     if not token or len(token.strip()) < 16:
         raise ServiceError("the service token must be at least 16 characters.")
     root = directory or services_dir()
     token_file = remote_token_file(service_id, instance, root)
     descriptor: Dict[str, Any] = {"protocol": PROTOCOL, "id": service_id, "instance": instance, "name": name,
                                   "placement": "remote", "origin": origin, "auth": {"tokenFile": str(token_file)},
-                                  "lifecycle": {"manager": "none"}, "installedAt": now_iso(), "installedBy": installed_by}
+                                  "lifecycle": {"manager": "none"}, "installedAt": now_iso(),
+                                  "installedBy": installed_by if installed_by is not None else
+                                  {"by": "person", "role": "operator", "tool": "fabric-service register-remote"}}
     if summary:
         descriptor["summary"] = summary
+    if runner is not None:
+        descriptor["runner"] = dict(runner)
+    if peer is not None:
+        descriptor["peer"] = dict(peer)
     if doctor:
         descriptor["commands"] = {"doctor": list(doctor)}
     problems = validate_descriptor(descriptor)

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

@@ -350,7 +350,8 @@ def register(args: argparse.Namespace) -> int:
         else {"manager": "none"},
         "paths": {"data": str(data), "logs": []},
         "fabricManifest": str(manifest),
-        "installedAt": fs.now_iso(), "installedBy": "sample_service.py register",
+        # DEC-0061: who installed it, by role and never by name — a person runs this register command.
+        "installedAt": fs.now_iso(), "installedBy": {"by": "person", "role": "operator", "tool": "sample_service.py register %s" % VERSION},
     }
     try:
         path = fs.write_descriptor(descriptor, Path(args.services_dir) if args.services_dir else None)

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/SKILL.md

@@ -5,9 +5,9 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode. Ships in one plugin with adapting-projects-to-fabric, whose scripts it reuses.
 metadata:
   author: PassionCode.ai
-  version: "0.23.0"
+  version: "0.25.0"
   contract-version: "0.1.0"
-  contract-commit: "fe55fc67cba1a9e34a736da7d148d4fe2a8fbfa0"
+  contract-commit: "a046f57cf46ea9e3da57ff8ce6a3ed4d26d8774b"
 ---
 
 # Creating Fabric-compatible agents
@@ -123,7 +123,7 @@ python3 <plugin-dir>/skills/adapting-projects-to-fabric/scripts/adapt_project.py
 The effect class is declared, never defaulted: ask the author what the agent does outside itself when the request
 does not say. Cost presets are only for a run whose cost varies; their amounts come from the author or measured runs.
 
-Pin exactly contract `0.1.0` at commit `fe55fc67cba1a9e34a736da7d148d4fe2a8fbfa0` and
+Pin exactly contract `0.1.0` at commit `a046f57cf46ea9e3da57ff8ce6a3ed4d26d8774b` and
 read the pinned guide before implementing protocol details. If this skill is installed
 without its sibling, the scaffolder is absent: create the bundle by hand from the pinned
 contract's `docs/guides/connecting-compatible-agents.md` and mark the structural check

package/plugins/fabric-agent-adapter/skills/working-with-fabric/SKILL.md

@@ -18,7 +18,7 @@ compatibility: >-
   this plugin; Codex and Kimi Code get the session-start preamble hook on the person's consent.
 metadata:
   author: PassionCode.ai
-  version: "0.23.0"
+  version: "0.25.0"
 ---
 
 # Working with Fabric

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/fabric_session.py

@@ -60,7 +60,7 @@ WATCH_MAX_BACKOFF_S = 900
 SESSION_ID = re.compile(r"[A-Za-z0-9._:-]{1,128}")
 LOOPBACK_ORIGIN = re.compile(r"http://127\.0\.0\.1:(\d{1,5})")
 LOCAL_ORIGIN = re.compile(r'"origin": "http://(?:127\.0\.0\.1|localhost)')
-VERSION = "0.23.0"
+VERSION = "0.25.0"
 HOSTS = {"claude": "Claude Code", "codex": "Codex", "kimi": "Kimi Code"}
 # A session Fabric launched. FABRIC_LAUNCHED_SESSION=1 is the marker Fabric is asked to set (need D6); the others are
 # what Fabric already gives a launched session (fabric sessionBundle.ts): only their NAMES are looked at, never a value