@passioncode-ai/fabric-agent-adapter 0.78.0 → 0.80.2

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

@@ -0,0 +1,358 @@
+"""The call queue and the load report of DEC-0104 (contract `src/agent-network.ts`, FAC-SEM-131 to FAC-SEM-133), as the
+contract's reference answers them: a node that hosts a job-backed agent queues its jobs per (agentRef, context) with
+these and reports its load as `service-load/1` under `extensions/load/0.1`. Part of the service kit (FAA-289, layer L3);
+the twin of fabric-load.mjs. Standard library only. Nothing here raises on what it reads, except `load_extension`, which
+refuses a declaration a reader would treat as not declared.
+
+- job_caller_key(accepted, credential): the opaque key of a job's caller (an accepted delegation's principal, its
+  outermost actor and a partner organization ending the chain; else the credential the node knows the caller by).
+- next_queued_job(queue, running, limits): the job the node starts next, or None (fairness between callers).
+- admit_job(queue, running, job, limits, retry_after_seconds): {admit: True}, or the `queue-full` refusal with its data.
+- queue_status_message(position, length), read_queue_position(status_message): `queued <position> of <length>`.
+- job_queue_rules(value): FAC-SEM-131 over {queue, running, limits, started}.
+- load_report_rules(report): FAC-SEM-132 on a `service-load/1` report; load_report_problems(report): its schema.
+- load_view(well_known), load_extension_rules(well_known): the declaration as a reader reads it, and FAC-SEM-133.
+- load_extension(path, window_seconds, limits): the `extensions` entry a service declares.
+
+The kit has no JSON Schema validator: the two shapes are written here from the schemas as the contract's validator
+reads them (ECMAScript's \\s in patterns, lengths in code points, `date-time` as ajv-formats' full mode). Times in the
+queue are UTC instants (`interop-common#/$defs/utcInstant`); times in the report are RFC 3339 read strictly (the
+contract's strictTime). The wording of a schema problem is the kit's, not ajv's."""
+from __future__ import annotations
+
+import math
+import re
+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_base import ServiceError  # noqa: E402
+from fabric_connections import date_time  # noqa: E402 - ajv-formats' date-time, as the contract's validator reads it
+from fabric_jsvalue import (  # noqa: E402
+    MISSING, _JS_SPACE, double, get, is_number, json_stringify, objects, safe_integer, same, show,
+)
+from fabric_time import parse_rfc3339_ms  # noqa: E402 - the contract's strictTime
+
+LOAD_EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/load/0.1"
+LOAD_REPORT_TYPE = "service-load/1"
+#: The refusal code, the same as fabric_interop_rules.QUEUE_FULL (a test holds them equal); not imported because the
+#: facade fabric_service, which re-exports this module, comes before the interop rules in the kit's order.
+_QUEUE_FULL = "queue-full"
+QUEUE_FULL_MESSAGE = "the agent's queue for this context is full: start again later"
+#: The longest queue a status message names (`queued <position> of <length>`, six digits).
+QUEUE_LENGTH_MAX = 999999
+DEFAULT_RETRY_AFTER_SECONDS = 60
+
+_UTC_INSTANT = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-5][0-9](?:\.[0-9]{1,3})?Z", re.ASCII)
+_QUEUED = re.compile(r"queued ([1-9][0-9]{0,5}) of ([1-9][0-9]{0,5})", re.ASCII)
+_ORIGIN_PATH = re.compile("/(?!/)[^%s]*" % re.escape(_JS_SPACE))
+_CONTEXT = re.compile(r"(?:personal|org:[A-Za-z0-9][A-Za-z0-9_-]{0,127})", re.ASCII)
+_KEY_PATH = "/extensions/" + LOAD_EXTENSION_KEY.replace("~", "~0").replace("/", "~1")
+_LIMITS = (("concurrency", 1, 1024), ("perCaller", 1, 1024), ("queueMax", 0, 100000))
+_ROW_COUNTS = ("queued", "running", "completed", "failed")
+
+
+def _utc_ms(value: Any) -> float:
+    """A UTC instant (`T`, `Z`, at most three fraction digits, a day that exists) in milliseconds, else NaN."""
+    return parse_rfc3339_ms(value) if isinstance(value, str) and _UTC_INSTANT.fullmatch(value) else math.nan
+
+
+def _strict_ms(value: Any) -> float:
+    return parse_rfc3339_ms(value) if isinstance(value, str) else math.nan
+
+
+def _utf16(value: str) -> bytes:
+    """A key that orders strings as JavaScript's `<` does: by UTF-16 code units."""
+    return value.encode("utf-16-be", "surrogatepass")
+
+
+def _string(value: Any) -> bool:
+    return isinstance(value, str)
+
+
+# --- The call queue (fabric-interop, DEC-0104) ---
+
+
+def job_caller_key(accepted: Any = MISSING, credential: Any = MISSING) -> Optional[str]:
+    """The key of a job's caller at a node that queues (DEC-0104), as the contract's jobCallerKey: for a call whose
+    delegation the node accepted (verify_delegation's answer), its `principal` and `caller` and the partner
+    organization when the chain ends in one (DEC-0090); for a call with no token, the credential the node knows the
+    caller by (a gate's pass with `principal: None` is that case too). A refused verdict has no key, and neither has
+    an unreadable call: None. The key is opaque; only equality matters."""
+    if isinstance(accepted, dict) and not (get(accepted, "ok") is True and get(accepted, "principal") is None):
+        principal, caller = get(accepted, "principal"), get(accepted, "caller")
+        if get(accepted, "ok") is not True or not _string(principal) or principal == "" or not _string(caller) or caller == "":
+            return None
+        chain = get(accepted, "chain")
+        chain = chain if isinstance(chain, list) else []
+        last = chain[-1] if chain else MISSING
+        partner = [last] if len(chain) > 1 and _string(last) and last.startswith("org:") else []
+        return json_stringify(["delegated", principal, caller] + partner)
+    return json_stringify(["credential", credential]) if _string(credential) and credential != "" else None
+
+
+def _limits_ok(limits: Any) -> bool:
+    if not isinstance(limits, dict):
+        return False
+    concurrency, per_caller, queue_max = get(limits, "concurrency"), get(limits, "perCaller"), get(limits, "queueMax")
+    return (all(safe_integer(n) and double(n) >= 1 for n in (concurrency, per_caller))
+            and safe_integer(queue_max) and double(queue_max) >= 0)
+
+
+def _waiting_job(job: Any) -> bool:
+    return isinstance(job, dict) and _string(get(job, "id")) and _string(get(job, "caller")) and math.isfinite(_utc_ms(get(job, "at")))
+
+
+def next_queued_job(queue: Any, running: Any, limits: Any) -> Optional[str]:
+    """The job the hosting node starts next for one (agentRef, context), or None (DEC-0104). Nothing starts while
+    `concurrency` jobs run (every running job holds a slot, its caller readable or not). Of the waiting jobs whose
+    caller runs fewer than `perCaller`, the one whose caller runs the fewest wins; between those callers, the one whose
+    oldest waiting job arrived first; within a caller, its oldest. Arrival ties break by id (UTF-16 order)."""
+    if not _limits_ok(limits):
+        return None
+    if (len(running) if isinstance(running, list) else 0) >= double(limits["concurrency"]):
+        return None
+    running_of: Dict[str, int] = {}
+    for job in objects(running):
+        if _string(get(job, "caller")):
+            running_of[job["caller"]] = running_of.get(job["caller"], 0) + 1
+    waiting = [job for job in objects(queue) if _waiting_job(job) and running_of.get(job["caller"], 0) < double(limits["perCaller"])]
+    waiting.sort(key=lambda job: (_utc_ms(job["at"]), _utf16(job["id"])))
+    best: Optional[Dict[str, Any]] = None
+    for job in waiting:
+        if best is None or running_of.get(job["caller"], 0) < running_of.get(best["caller"], 0):
+            best = job
+    return None if best is None else best["id"]
+
+
+def admit_job(queue: Any, running: Any, job: Any, limits: Any, retry_after_seconds: Any = MISSING) -> Dict[str, Any]:
+    """Whether a start is admitted (DEC-0104): it is when the job would start at once (next_queued_job over the queue
+    with it added answers its id), or when fewer than `queueMax` jobs wait; otherwise {admit: False, error} with the
+    `queue-full` refusal and its `retryAfterSeconds` (1 to 3600, else 60). Unreadable limits or job refuse."""
+    waiting = objects(queue)
+    if _limits_ok(limits) and _waiting_job(job) and (
+            next_queued_job(waiting + [job], running, limits) == job["id"] or len(waiting) < double(limits["queueMax"])):
+        return {"admit": True}
+    after = retry_after_seconds if safe_integer(retry_after_seconds) and 1 <= double(retry_after_seconds) <= 3600 else DEFAULT_RETRY_AFTER_SECONDS
+    return {"admit": False, "error": {"code": _QUEUE_FULL, "message": QUEUE_FULL_MESSAGE,
+                                      "data": {"retryable": True, "retryAfterSeconds": int(after)}}}
+
+
+def queue_status_message(position: Any, length: Any) -> Optional[str]:
+    """The `statusMessage` of a waiting job (DEC-0104): `queued <position> of <length>`, 1 is next, 1 <= position <=
+    length <= 999999; None for anything else."""
+    if not (safe_integer(position) and safe_integer(length)):
+        return None
+    if not 1 <= double(position) <= double(length) <= QUEUE_LENGTH_MAX:
+        return None
+    return "queued %d of %d" % (int(position), int(length))
+
+
+def read_queue_position(status_message: Any) -> Optional[Dict[str, int]]:
+    """A waiting job's place, read from its `statusMessage`, or None when it is not the queue's grammar."""
+    match = _QUEUED.fullmatch(status_message) if _string(status_message) else None
+    if not match:
+        return None
+    position, length = int(match.group(1)), int(match.group(2))
+    return {"position": position, "length": length} if 1 <= position <= length else None
+
+
+def _finding(code: str, instance_path: str, message: str) -> Dict[str, str]:
+    return {"code": code, "instancePath": instance_path, "message": message}
+
+
+def job_queue_rules(value: Any) -> List[Dict[str, str]]:
+    """FAC-SEM-131 on {queue, running, limits, started} (`started`: the id the node started, or None): it is
+    next_queued_job's."""
+    want = next_queued_job(get(value, "queue"), get(value, "running"), get(value, "limits"))
+    started = get(value, "started")
+    if same(None if started is MISSING else started, want):
+        return []
+    return [_finding("FAC-SEM-131", "/started", "nothing may start now" if want is None else "the job to start is %s" % show(want))]
+
+
+# --- The load report (DEC-0104) ---
+
+
+def load_report_rules(report: Any) -> List[Dict[str, str]]:
+    """FAC-SEM-132 on a `service-load/1` report: windows in order one `windowSeconds` apart, none after `generatedAt`,
+    one row per context, p50 at most p95, a run time only where a job ended."""
+    findings: List[Dict[str, str]] = []
+    flag = lambda path, message: findings.append(_finding("FAC-SEM-132", path, message))  # noqa: E731
+    seconds = get(report, "windowSeconds")
+    step = double(seconds) * 1000 if safe_integer(seconds) else math.nan
+    generated = _strict_ms(get(report, "generatedAt"))
+    previous: Any = MISSING
+    for index, window in enumerate(objects(get(report, "windows"))):
+        start = _strict_ms(get(window, "start"))
+        if start > generated:
+            flag("/windows/%d/start" % index, "a window starts after the report was generated")
+        if previous is not MISSING and start - previous != step:
+            flag("/windows/%d/start" % index, "windows are not in order one windowSeconds apart")
+        previous = start
+        seen = set()
+        for at, row in enumerate(objects(get(window, "byContext"))):
+            path = "/windows/%d/byContext/%d" % (index, at)
+            context = get(row, "context")
+            if _string(context) and context in seen:
+                flag(path + "/context", "context %s appears twice in one window" % show(context))
+            if _string(context):
+                seen.add(context)
+            for name in ("waitMs", "runMs"):
+                pct = get(row, name)
+                p50, p95 = get(pct, "p50"), get(pct, "p95")
+                if isinstance(pct, dict) and is_number(p50) and is_number(p95) and double(p50) > double(p95):
+                    flag("%s/%s" % (path, name), "p50 is above p95")
+            if isinstance(get(row, "runMs"), dict) and same(get(row, "completed"), 0) and same(get(row, "failed"), 0):
+                flag(path + "/runMs", "a run time with no job ended in the window")
+    return findings
+
+
+def _integer(value: Any, low: float, high: Optional[float], at: str, errors: List[str]) -> None:
+    """JSON Schema's integer with its bounds, as ajv reads it: a number with no fraction (2.0 is one), never a bool."""
+    if not is_number(value) or not math.isfinite(double(value)) or double(value) != math.floor(double(value)):
+        errors.append("%s type" % at)
+    elif double(value) < low:
+        errors.append("%s minimum" % at)
+    elif high is not None and double(value) > high:
+        errors.append("%s maximum" % at)
+
+
+def _members(value: Dict[str, Any], allowed: tuple, required: tuple, at: str, errors: List[str]) -> None:
+    errors.extend("%s/%s additionalProperties" % (at, key) for key in value if key not in allowed)
+    errors.extend("%s required %s" % (at or "/", key) for key in required if key not in value)
+
+
+def _timestamp(value: Any, at: str, errors: List[str]) -> None:
+    if not _string(value):
+        errors.append("%s type" % at)
+    elif not date_time(value):
+        errors.append("%s format" % at)
+
+
+def _percentiles(value: Any, at: str, errors: List[str]) -> None:
+    if not isinstance(value, dict):
+        errors.append("%s type" % at)
+        return
+    _members(value, ("p50", "p95"), ("p50", "p95"), at, errors)
+    for name in ("p50", "p95"):
+        if name in value:
+            _integer(value[name], 0, None, "%s/%s" % (at, name), errors)
+
+
+def _row_problems(row: Any, at: str, errors: List[str]) -> None:
+    if not isinstance(row, dict):
+        errors.append("%s type" % at)
+        return
+    _members(row, ("context",) + _ROW_COUNTS + ("waitMs", "runMs"), ("context",) + _ROW_COUNTS, at, errors)
+    if "context" in row and not (_string(row["context"]) and _CONTEXT.fullmatch(row["context"])):
+        errors.append("%s/context %s" % (at, "pattern" if _string(row["context"]) else "type"))
+    for name in _ROW_COUNTS:
+        if name in row:
+            _integer(row[name], 0, None, "%s/%s" % (at, name), errors)
+    for name in ("waitMs", "runMs"):
+        if name in row:
+            _percentiles(row[name], "%s/%s" % (at, name), errors)
+
+
+def load_report_problems(report: Any) -> List[str]:
+    """service-load.schema.json: what makes `report` not a `service-load/1` report, each as `<path> <keyword>`; empty
+    for a valid one. Counts and durations only: a member the schema does not name (a caller, a job id) is refused."""
+    if not isinstance(report, dict):
+        return ["/ type"]
+    errors: List[str] = []
+    _members(report, ("type", "generatedAt", "windowSeconds", "windows"), ("type", "generatedAt", "windowSeconds", "windows"), "", errors)
+    if "type" in report and not same(report["type"], LOAD_REPORT_TYPE):
+        errors.append("/type const")
+    if "generatedAt" in report:
+        _timestamp(report["generatedAt"], "/generatedAt", errors)
+    if "windowSeconds" in report:
+        _integer(report["windowSeconds"], 60, 86400, "/windowSeconds", errors)
+    windows = report.get("windows", MISSING)
+    if windows is not MISSING and not isinstance(windows, list):
+        errors.append("/windows type")
+    elif isinstance(windows, list):
+        if len(windows) > 168:
+            errors.append("/windows maxItems")
+        for index, window in enumerate(windows):
+            at = "/windows/%d" % index
+            if not isinstance(window, dict):
+                errors.append("%s type" % at)
+                continue
+            _members(window, ("start", "byContext"), ("start", "byContext"), at, errors)
+            if "start" in window:
+                _timestamp(window["start"], at + "/start", errors)
+            rows = window.get("byContext", MISSING)
+            if rows is not MISSING and not isinstance(rows, list):
+                errors.append("%s/byContext type" % at)
+            elif isinstance(rows, list):
+                if len(rows) > 64:
+                    errors.append("%s/byContext maxItems" % at)
+                for row_index, row in enumerate(rows):
+                    _row_problems(row, "%s/byContext/%d" % (at, row_index), errors)
+    return errors
+
+
+def _declaration_problems(value: Any) -> List[str]:
+    """service-load-extension.schema.json, each problem as `<path> <keyword>`; empty for a valid declaration."""
+    if not isinstance(value, dict):
+        return ["/ type"]
+    errors: List[str] = []
+    _members(value, ("path", "windowSeconds", "limits"), ("path", "windowSeconds", "limits"), "", errors)
+    path = value.get("path", MISSING)
+    if path is not MISSING:
+        if not _string(path):
+            errors.append("/path type")
+        else:
+            if len(path) > 256:  # code points, as ajv counts them; the originPath's own 2048 is wider
+                errors.append("/path maxLength")
+            if not _ORIGIN_PATH.fullmatch(path):
+                errors.append("/path pattern")
+    if "windowSeconds" in value:
+        _integer(value["windowSeconds"], 60, 86400, "/windowSeconds", errors)
+    limits = value.get("limits", MISSING)
+    if limits is not MISSING:
+        if not isinstance(limits, dict):
+            errors.append("/limits type")
+        else:
+            _members(limits, tuple(name for name, _, _ in _LIMITS), tuple(name for name, _, _ in _LIMITS), "/limits", errors)
+            for name, low, high in _LIMITS:
+                if name in limits:
+                    _integer(limits[name], low, high, "/limits/%s" % name, errors)
+    return errors
+
+
+def load_view(well_known: Any) -> Dict[str, Any]:
+    """The load declaration as a reader reads it (DEC-0104): `declared` when the extension key is present, `valid` when
+    its value is the schema's, `load` the declaration when valid (else None) and `errors` its problems. A reader treats
+    an invalid value as not declared and reports it (FAC-SEM-133)."""
+    extensions = get(well_known, "extensions")
+    if not isinstance(extensions, dict) or LOAD_EXTENSION_KEY not in extensions:
+        return {"declared": False, "valid": False, "load": None, "errors": []}
+    value = extensions[LOAD_EXTENSION_KEY]
+    errors = _declaration_problems(value)
+    return {"declared": True, "valid": not errors, "load": None if errors else value, "errors": errors}
+
+
+def load_extension_rules(well_known: Any) -> List[Dict[str, str]]:
+    """FAC-SEM-133 on a well-known document: a value under the load extension key is valid against
+    service-load-extension.schema.json; one finding at the key otherwise."""
+    view = load_view(well_known)
+    if not view["declared"] or view["valid"]:
+        return []
+    return [_finding("FAC-SEM-133", _KEY_PATH, "the load declaration is invalid (%s); a reader treats it as not declared "
+                                               "and reports it (DEC-0104)" % "; ".join(view["errors"]))]
+
+
+def load_extension(path: Any, window_seconds: Any, limits: Any) -> Dict[str, Any]:
+    """The `extensions` entry a service declares (DEC-0104): where it serves its `service-load/1` report (an origin
+    path, served under the descriptor token like the usage report), the report's window and the queue's limits per
+    (agentRef, context). Raises ServiceError on a declaration a reader would treat as not declared."""
+    value = {"path": path, "windowSeconds": window_seconds, "limits": dict(limits) if isinstance(limits, dict) else limits}
+    problems = _declaration_problems(value)
+    if problems:
+        raise ServiceError("Load declaration: %s." % "; ".join(problems))
+    return {LOAD_EXTENSION_KEY: value}

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

@@ -73,8 +73,42 @@ class InstanceLock:
     #: a file is allowed there).
     WINDOWS_LOCK_OFFSET = 1 << 30
 
+    #: How many times acquire re-opens service.lock when the file it locked is no longer the file at its path (a
+    #: folder swapped under it by a data import), before it gives up with an error naming the path (FAA-293).
+    INODE_RETRIES = 3
+
     def acquire(self) -> "InstanceLock":
         ensure_private_dir(self.path.parent)
+        for _ in range(self.INODE_RETRIES):
+            if self._acquire_once():
+                return self
+        raise ServiceError("%s kept moving while it was locked (a folder swapped under the data folder?): no copy "
+                           "holds a file that is no longer at its path; start again once the folder is settled." % self.path)
+
+    def _locked_file_is_at_path(self, fd: int) -> bool:
+        """The inode this copy locked is the file at the path now (FAA-293). Windows does not rename a folder holding
+        an open file, and its lock is a byte range on this handle, so the check is POSIX only."""
+        if WINDOWS:
+            return True
+        try:
+            here, held = os.stat(str(self.path)), os.fstat(fd)
+        except FileNotFoundError:
+            return False
+        return (here.st_dev, here.st_ino) == (held.st_dev, held.st_ino)
+
+    def _let_go(self, fd: int) -> None:
+        try:
+            os.close(fd)
+        except OSError:
+            pass
+        name, self._name = self._name, None
+        if name is not None:
+            try:
+                _drop_lock_name(name)
+            except OSError:
+                pass
+
+    def _acquire_once(self) -> bool:
         fd = os.open(str(self.path), os.O_RDWR | os.O_CREAT | _O_BINARY, 0o600)
         try:
             if WINDOWS:
@@ -92,6 +126,9 @@ class InstanceLock:
             if exc.errno in (errno.EWOULDBLOCK, errno.EAGAIN, errno.EACCES, getattr(errno, "EDEADLOCK", -1)):
                 raise AlreadyRunning(_read_pid(self.path), self.path) from None
             raise
+        if not self._locked_file_is_at_path(fd):  # another copy may hold the file at the path: re-open that one
+            os.close(fd)
+            return False
         try:
             self._name = _hold_lock_name(self.path)
         except BaseException:
@@ -114,8 +151,11 @@ class InstanceLock:
                     except OSError:  # as with the close: nothing to add to the first error
                         pass
             raise
+        if not self._locked_file_is_at_path(fd):  # swapped while the pid was written: this copy holds nothing real
+            self._let_go(fd)
+            return False
         self._fd = fd
-        return self
+        return True
 
     def release(self) -> None:
         if self._fd is not None:

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

@@ -366,6 +366,10 @@ class Client:
                 if answer is not None:
                     answer["attempts"] = attempts
                     return answer
+                if outcome == "foreign-user":  # FAA-257: the fallback would go to the same refused listener
+                    raise OpenRouterError("The base URL's port is held by another OS account's process, or its owner "
+                                          "cannot be told; nothing was sent (DEC-0154 HA-2)", kind="foreign-user",
+                                          attempts=attempts)
                 if outcome in _STOP_AT_ONCE.values():
                     raise OpenRouterError("OpenRouter refused the key or the request (%s)" % status, kind=outcome,
                                           attempts=attempts)
@@ -390,6 +394,8 @@ class Client:
                 # the provider may have billed a call whose answer never arrived whole (a cut connection looks the
                 # same as a refused one from here): counted, never as $0; over-counting is the safe side
                 self.ledger.record(self._unmeasured(asked, task_run_id, worst))
+            if err.kind == "foreign-user":  # nothing was sent: nothing billed, and no other model there (FAA-257)
+                return "foreign-user", err.status, None, None
             return ("retry" if err.kind in ("connection", "timeout") else "refused"), err.status, None, None
         status = response.status
         if status in _STOP_AT_ONCE:

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

@@ -1,6 +1,6 @@
 """peer_owner: which OS account owns each end of a loopback TCP connection.
 
-    peer_owner 1.1.0+kit.3: Observatory's peer_owner 1.1.0, vendored into the Fabric service kit as `fabric_peer_owner` (layer L0;
+    peer_owner 1.1.0+kit.4: Observatory's peer_owner 1.1.0, vendored into the Fabric service kit as `fabric_peer_owner` (layer L0;
     DEC-0154 HA-2, FAA-226) from Project Observatory's `observatory/engine/peer_owner.py` at
     commit f86f0622 (passioncode-ai/project-observatory-dashboard, the same licence). It differs
     from that file in this paragraph, in `Owner` and `Row` (NamedTuples here where it has
@@ -19,7 +19,8 @@
     macOS: the sysctl calibration also requires a child process's listener, an empty netstat reads as
     `TABLE_RESTRICTED`, and a caller may vouch for a listener with a pid it started (`pid_listens`,
     `parse_lsof_listeners`, `LSOF`, `CheckedHTTPConnection(vouch_pid=...)`, `own_connection(vouch_pid=...)`); since kit.3
-    the child's port is waited on with `selectors` and read under one deadline (FAA-273).
+    the child's port is waited on with `selectors` and read under one deadline (FAA-273); since kit.4 a number is ASCII
+    digits only and a netstat with only its header reads as `TABLE_RESTRICTED` (FAA-273 items 3 and 4).
     A limit /proc sets: it carries a socket's creator and no pid, so a listening socket that root
     created and handed to another account (systemd socket activation with User=) reads as root's. Standard library only, no import of another kit module.
     The kit's tests are `test/test_fabric_peer_owner.py`, over `test/fixtures/peer-owner/`;
@@ -110,7 +111,7 @@ import time
 from typing import NamedTuple, Optional, Tuple
 
 # This file's own version, for projects that copy it; not the engine's (that is configuration.VERSION).
-PEER_OWNER_VERSION = "1.1.0+kit.3"  # Observatory's 1.1.0 with the kit's differences above
+PEER_OWNER_VERSION = "1.1.0+kit.4"  # Observatory's 1.1.0 with the kit's differences above
 
 THIS_ACCOUNT = "this-account"
 ANOTHER_ACCOUNT = "another-account"
@@ -231,6 +232,11 @@ def classify(uid: Optional[int], pid: Optional[int], *, method: str, own_uid: Op
 
 # -- parsers: pure functions over captured text or bytes (the tests' fixtures) ---------------------------------------
 
+def _ascii_digits(text: str) -> bool:
+    """`[0-9]+` as the Node twin reads a number; `str.isdigit` also takes `٤` and `²` (FAA-273 item 4)."""
+    return text != "" and text.isascii() and text.isdigit()
+
+
 def parse_netstat(text: str) -> list[Row]:
     """`netstat -anv -p tcp` on macOS. Process names may hold spaces ("Some App:123"), so the
     `process:pid` column is what is left between the leading and the trailing columns, both
@@ -246,6 +252,10 @@ def parse_netstat(text: str) -> list[Row]:
     # "Local Address" and "Foreign Address" are two header words each and one data column each.
     leading = at - sum(1 for w in names[:at] if w == "Address")
     trailing = len(names) - at - 1
+    if not any(line.split()[:1] and line.split()[0].startswith("tcp") for line in lines[header + 1:]):
+        # The caller's own connection is in any table it can see: a header and no tcp row is the restricted table
+        # (FAA-273 item 3), not `no-row`.
+        raise TableUnreadable(f"{TABLE_RESTRICTED}: netstat printed only its header to this process")
     rows: list[Row] = []
     for line in lines[header + 1:]:
         tok = line.split()
@@ -259,7 +269,7 @@ def parse_netstat(text: str) -> list[Row]:
         pid = None
         if ":" in process:
             tail = process.rsplit(":", 1)[1]
-            pid = int(tail) if tail.isdigit() else None
+            pid = int(tail) if _ascii_digits(tail) else None
         rows.append(Row(local, remote, tok[5] == "LISTEN", None, pid, tok[5] == "TIME_WAIT"))
     return rows
 
@@ -283,7 +293,7 @@ def parse_lsof_listeners(text: str) -> list[tuple[str, int]]:
         if not line.startswith("n") or ":" not in line:
             continue
         host, port = line[1:].rsplit(":", 1)
-        if port.isdigit():
+        if _ascii_digits(port):
             found.append((norm_host(host.strip("[]")), int(port)))
     return found
 
@@ -291,7 +301,7 @@ def parse_lsof_listeners(text: str) -> list[tuple[str, int]]:
 def parse_ps_uid(text: str) -> Optional[int]:
     """`ps -o uid= -p PID`: one number, or nothing when the process is gone."""
     text = text.strip()
-    return int(text) if text.isdigit() else None
+    return int(text) if _ascii_digits(text) else None
 
 
 def parse_proc_net_tcp(text: str, *, family: int, byteorder: Optional[str] = None) -> list[Row]:
@@ -540,7 +550,7 @@ def _child_listener_seen(rows_of) -> Optional[bool]:
     port = None
     try:
         line = _child_line(child, deadline)
-        if line is None or not line.strip().isdigit():
+        if line is None or not _ascii_digits(line.strip()):
             return None
         port = int(line.strip())
         try:

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

@@ -6,6 +6,7 @@ only. The dashboard kit's fabric-button.js carries its own copy of the name and
 
 It reads as the contract's ECMAScript does (FAA-136): ECMAScript's whitespace (Python's `\\s` also takes U+0085 and
 U+001C to U+001F, and not U+FEFF), `.` stopping at every line terminator, ASCII case folding, an ASCII word boundary."""
+# Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 
 from __future__ import annotations
 
@@ -142,7 +143,7 @@ def _percent_encode(text: str, also: str) -> str:
     return "".join(out)
 
 
-def _url_parts(value: str) -> Tuple[str, str, str]:
+def url_parts(value: str) -> Tuple[str, str, str]:
     """The password, query and fragment of an absolute URL as WHATWG URL parsing splits them, read by hand: urlsplit
     refuses a `[` or `]` outside an IPv6 host (`<https>://u:p[w@h/`), where `new URL` reads the password (0.56.0 unit
     r7). The fragment starts at the first `#`, the query at the first `?` before it. A special scheme's authority starts
@@ -166,6 +167,9 @@ def _url_parts(value: str) -> Tuple[str, str, str]:
             _percent_encode(fragment, "`"))
 
 
+_url_parts = url_parts  # the name before FAA-250, kept for code that reached it
+
+
 def secret_url(value: str) -> bool:
     """Whether a URL an MCP entry or a launch names carries a credential (LC-21): anything secret_argument finds, a
     password in its user information, or a query or fragment parameter whose name can only carry a credential and has
@@ -177,7 +181,7 @@ def secret_url(value: str) -> bool:
     value = re.sub(r"[\t\n\r]", "", value.strip(_C0_OR_SPACE))
     if not _SCHEME.match(value):
         return False  # not an absolute URL (WHATWG URL parsing refuses it)
-    password, query, fragment = _url_parts(value)
+    password, query, fragment = url_parts(value)
     if password:
         return True
     for part in (query, fragment):

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

@@ -22,6 +22,7 @@ from fabric_time import DAY_MS as _DAY_MS, utc_date_ms as _utc_date_ms  # noqa:
 from fabric_base import (  # noqa: F401
     PROTOCOL,
     EXTENSION_KEY,
+    PRIMARY_CAPABILITY,
     SUPERVISOR_ENV,
     DRAIN_SECONDS,
     _ID,
@@ -196,6 +197,24 @@ from fabric_connections import (  # noqa: F401
     connections_rules,
     connections_view,
 )
+from fabric_load import (  # noqa: F401 - the call queue and the load report (DEC-0104, FAA-289)
+    LOAD_EXTENSION_KEY,
+    LOAD_REPORT_TYPE,
+    QUEUE_FULL_MESSAGE,
+    QUEUE_LENGTH_MAX,
+    DEFAULT_RETRY_AFTER_SECONDS,
+    job_caller_key,
+    next_queued_job,
+    admit_job,
+    queue_status_message,
+    read_queue_position,
+    job_queue_rules,
+    load_report_rules,
+    load_report_problems,
+    load_view,
+    load_extension_rules,
+    load_extension,
+)
 from fabric_descriptor import (  # noqa: F401
     DASHBOARD_EXTENSION_KEY,
     DASHBOARD_KIT,
@@ -230,7 +249,9 @@ from fabric_descriptor import (  # noqa: F401
     fabric_button_presence,
     placement_of,
     remote_origin_problems,
+    port_listener_refusal,
     port_of,
+    port_owner,
     NO_SOURCE_REPOSITORY,
     NoSourceRepositoryWarning,
     names_repository,
@@ -319,6 +340,9 @@ from fabric_supervisors import (  # noqa: F401
     launchd_loaded,
     launchd_pid,
     fetch_well_known,
+    well_known_of,
+    job_well_known_of,
+    ForeignUserAnswer,
     _OVERRIDE_ROW,
     launchd_override,
     launchd_install,