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

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

@@ -13,7 +13,8 @@ not re-export this module, so a service that does not run per context keeps the
 An organization's instance whose context the record does not pin (``organizations``, DEC-0127) still starts: the helper
 checks the placement and its share grant, not the pin (decision D5 of 0.52.0). Its tokens are refused instead:
 ``fabric_estate.hub_key_certified`` reads a context's hub keys only while the record pins that organization (DL-14a,
-DEC-0128), so the service passes ``estate_context=info["context"]`` to its delegation gate. The contract lets Fabric
+DEC-0128), so the service passes ``context_gate_options(info, record)`` (its context and its pin's issuer, FAA-150) to its
+delegation gate. The contract lets Fabric
 write ``organizations`` only once every reader is pinned at or after DEC-0127, so a refusal at start would stop every
 organization instance on today's records."""
 from __future__ import annotations
@@ -33,7 +34,8 @@ if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from
 from fabric_base import ServiceError, _INSTANCE  # noqa: E402
 from fabric_descriptor import descriptor_path  # noqa: E402
 from fabric_estate import parse_context  # noqa: E402
-from fabric_lock import InstanceLock, hold_single_instance  # noqa: E402
+from fabric_lock import (InstanceLock, LOCK_BACKOFF_FIRST_SECONDS, LOCK_BACKOFF_MAX_SECONDS, hold_single_instance,  # noqa: E402
+                         lock_wait_budget_seconds, supervisor_marker)
 from fabric_paths import atomic_write, instance_dirs  # noqa: E402
 from fabric_share import instance_share_grant  # noqa: E402
 from fabric_time import clock_ms  # noqa: E402
@@ -125,9 +127,49 @@ def context_instance(service_id: str, context: Any, *, record: Optional[Dict[str
     return answer
 
 
-def _refuse(service_id: Any, context: Any, code: str) -> None:
-    print("%s will not run for %s (%s): %s." % (service_id, _shown(context), code, _REASONS[code]), file=sys.stderr, flush=True)
-    raise SystemExit(EXIT_CONTEXT_REFUSED)
+def context_gate_options(info: Any, record: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """What ``delegation_gate`` takes from this instance's context (FAA-150): ``estate_context``, and for an organization
+    whose context ``record`` pins, ``issuer``: the pin's context issuer (DL-14a, DEC-0128), so an organization's instance
+    refuses a token the personal hub key signed without wiring either by hand. ``info`` is ``context_instance``'s answer
+    (or ``hold_context_instance``'s); ``record`` the verified estate revision applied. Spread it after the service's own
+    estate issuer: ``delegation_gate(..., **{"issuer": estate_issuer, **context_gate_options(info, record)})``. Raises
+    ContextRefused (``context-invalid``) for an answer with no context."""
+    context = info.get("context") if isinstance(info, dict) else None
+    parsed = parse_context(context)
+    if parsed is None:
+        raise ContextRefused("context-invalid")
+    options: Dict[str, Any] = {"estate_context": context}
+    pins = record.get("organizations") if isinstance(record, dict) else None
+    if parsed["kind"] == "org" and isinstance(pins, list):
+        for pin in pins:
+            if isinstance(pin, dict) and pin.get("org") == context and isinstance(pin.get("iss"), str):
+                options["issuer"] = pin["iss"]
+                break
+    return options
+
+
+def _refuse(service_id: Any, context: Any, code: str, wait_seconds: Optional[float] = 0.0, *,
+            sleep: Callable[[float], None] = time.sleep, clock: Callable[[], float] = time.monotonic,
+            env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None) -> None:
+    """One sentence naming the code, then exit 78. Under a supervisor that restarts on exit (launchd's KeepAlive with
+    ThrottleInterval 10, systemd's Restart=always) an exit at once is a respawn every few seconds, forever (FAA-279);
+    so a supervised copy first waits the lock's back-off (0.5 s doubling to 30 s, 300 s in all), holding nothing, and
+    exits 78 when it runs out: a few restarts an hour. ``wait_seconds`` overrides the choice as the lock's does."""
+    if wait_seconds is None:
+        wait_seconds = lock_wait_budget_seconds(supervisor_marker(env, argv))
+    wait_seconds = max(0.0, wait_seconds)
+    tail = " Waiting %.0f s before exiting, so its supervisor does not restart it every few seconds." % wait_seconds \
+        if wait_seconds > 0 else ""
+    print("%s will not run for %s (%s): %s.%s" % (service_id, _shown(context), code, _REASONS[code], tail),
+          file=sys.stderr, flush=True)
+    deadline = clock() + wait_seconds
+    delay = LOCK_BACKOFF_FIRST_SECONDS
+    while True:
+        remaining = deadline - clock()
+        if remaining <= 0:
+            raise SystemExit(EXIT_CONTEXT_REFUSED)
+        sleep(min(delay, remaining))
+        delay = min(delay * 2, LOCK_BACKOFF_MAX_SECONDS)
 
 
 def _marker_matches(path: Path, expected: Dict[str, str]) -> Optional[bool]:
@@ -152,7 +194,7 @@ def hold_context_instance(service_id: str, context: Any, *, record: Optional[Dic
                           env: Optional[Dict[str, str]] = None, argv: Optional[Sequence[str]] = None,
                           services_directory: Optional[Path] = None) -> Tuple[Dict[str, Any], InstanceLock]:
     """Run as ``context``'s one instance, before any side effect (brief D17): ``context_instance`` (a refusal prints one
-    sentence naming the code and exits 78, nothing created); then ``hold_single_instance`` on the instance's data
+    sentence naming the code and exits 78, nothing created; a supervised copy backs off first, FAA-279); then ``hold_single_instance`` on the instance's data
     folder (its markers, its supervised wait, its exit 75); then the marker ``<data>/fabric-context.json``: absent, it
     is written (0600, atomic); equal, it is kept; another context or instance, or unreadable, releases the lock and
     exits 78 (``context-mismatch``). Returns the instance and the held lock."""
@@ -160,7 +202,7 @@ def hold_context_instance(service_id: str, context: Any, *, record: Optional[Dic
         info = context_instance(service_id, context, record=record, machine_id=machine_id, agent_ref=agent_ref, at=at,
                                 personal_instance=personal_instance, services_directory=services_directory)
     except ContextRefused as refused:
-        _refuse(service_id, context, refused.code)
+        _refuse(service_id, context, refused.code, wait_seconds, sleep=sleep, clock=clock, env=env, argv=argv)
     lock = hold_single_instance(info["dirs"]["data"], wait_seconds, sleep=sleep, clock=clock, env=env, argv=argv)
     expected = {"service": service_id, "instance": info["instance"], "context": context}
     marker = Path(info["dirs"]["data"]) / CONTEXT_MARKER
@@ -173,5 +215,5 @@ def hold_context_instance(service_id: str, context: Any, *, record: Optional[Dic
         raise
     if matches is False:
         lock.release()
-        _refuse(service_id, context, "context-mismatch")
+        _refuse(service_id, context, "context-mismatch", wait_seconds, sleep=sleep, clock=clock, env=env, argv=argv)
     return info, lock

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

@@ -1,5 +1,6 @@
 """How a service is found (fabric-service/0.1): its descriptor, peers and app descriptors (DEC-0061, DEC-0069),
 build identity and the well-known document, the loopback HTTP server. Part of the service kit (FAA-65, layer L3)."""
+# Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 from __future__ import annotations
 
 import hashlib
@@ -7,6 +8,7 @@ import http.server
 import json
 import os
 import re
+import socket
 import socketserver
 import subprocess
 import warnings
@@ -29,6 +31,7 @@ from fabric_base import (
     expand,
     now_iso,
 )
+import fabric_peer_owner  # noqa: E402 - L0: who listens on a port (DEC-0154 HA-2, FAA-225)
 from fabric_paths import (
     atomic_write,
     ensure_private_dir,
@@ -477,8 +480,35 @@ def source_refusal(descriptor: Dict[str, Any], directory: Optional[Path] = None)
     return "Descriptor %s %s. %s" % (me, NO_SOURCE_REPOSITORY, PASS_SOURCE)
 
 
-def write_descriptor(descriptor: Dict[str, Any], directory: Optional[Path] = None, *, _stacklevel: int = 2) -> Path:
-    """Installer-only. Refuses a port or id.instance another descriptor claims (a port is a claim).
+def port_owner(port: int) -> Optional[Tuple[str, Optional[int]]]:
+    """Who listens on 127.0.0.1:<port> now, as (kind, uid) from the kit's fabric_peer_owner, or None when a plain bind
+    of that address succeeds (nothing holds it, and the socket table is not read). FAA-225, DEC-0154 HA-2."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+        try:
+            probe.bind(("127.0.0.1", port))
+            return None
+        except OSError:
+            pass
+    owner = fabric_peer_owner.listener(port)
+    return owner.kind, owner.uid
+
+
+def port_listener_refusal(port: int, reader: Optional[Any] = None) -> Optional[str]:
+    """Why an install may not take ``port``: another OS account listens on it (FAA-225). This account, the system
+    (launchd holds a socket-activated job's socket), nobody and an unreadable table pass: the refusal is for a port
+    that is surely another account's. The recorded port per account and its claim file wait on contract DEC-0160."""
+    found = (reader or port_owner)(port)
+    if not found or found[0] != fabric_peer_owner.ANOTHER_ACCOUNT:
+        return None
+    uid = " (uid %d)" % found[1] if isinstance(found[1], int) else ""
+    return ("Port %d is listened on by another OS account%s: choose a port no other account holds (DEC-0154, "
+            "FAA-225)." % (port, uid))
+
+
+def write_descriptor(descriptor: Dict[str, Any], directory: Optional[Path] = None, *, _stacklevel: int = 2,
+                     port_owner: Optional[Any] = None) -> Path:
+    """Installer-only. Refuses a port or id.instance another descriptor claims (a port is a claim), and a port another
+    OS account listens on (FAA-225; ``port_owner(port) -> (kind, uid) | None`` reads it, the kit's own by default).
 
     FAA-198: a new descriptor names its ``source.repository``; rewriting one already installed without it only
     warns (``NoSourceRepositoryWarning``), so an installed agent's update keeps working."""
@@ -505,6 +535,9 @@ def write_descriptor(descriptor: Dict[str, Any], directory: Optional[Path] = Non
             continue
         if other_port == port:
             raise ServiceError("Port %d is already claimed by %s (%s)." % (port, key, path))
+    held = port_listener_refusal(port, port_owner) if port is not None else None
+    if held:
+        raise ServiceError(held)
     ensure_private_dir(root)
     target = descriptor_path(descriptor["id"], descriptor["instance"], root)
     atomic_write(target, (json.dumps(descriptor, indent=2, ensure_ascii=False) + "\n").encode(), 0o600)

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

@@ -28,6 +28,7 @@ The transport is injected in tests: `transport(method, url, headers, body, timeo
 `(status, headers, body_bytes)` or raises `OSError` (a connection error, `TimeoutError` included) or `HttpError`.
 Standard library only. Part of the service kit (FAA-65, layer L4).
 """
+# Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 from __future__ import annotations
 
 import datetime as _dt
@@ -64,7 +65,7 @@ class HttpError(Exception):
     refused URL or a body over the cap; `url` is redacted; `body` holds at most 2048 bytes of an answer's body."""
 
     def __init__(self, message: str, *, status: Optional[int] = None, url: str = "", attempts: int = 0,
-                 retry_after_s: Optional[float] = None, body: bytes = b"", kind: str = "http"):
+                 retry_after_s: Optional[float] = None, body: bytes = b"", kind: str = "http", reason: Optional[str] = None):
         super().__init__(message)
         self.status = status
         self.url = url
@@ -72,6 +73,9 @@ class HttpError(Exception):
         self.retry_after_s = retry_after_s
         self.body = bytes(body[:2048])
         self.kind = kind  # http (an answer), connection, timeout, too-large, refused, foreign-user
+        #: For foreign-user, why (FAA-272): `table-restricted` (this process sees no other process's sockets, which
+        #: never clears), the owner's kind (`another-account`, `system`) or the check's reason (`no-row`).
+        self.reason = reason
 
 
 class Response:
@@ -385,7 +389,10 @@ def urllib_transport(method: str, url: str, headers: Dict[str, str], body: Optio
         return _send(req, timeout_s, max_bytes, end, watchdog)
     except _po.ListenerRefused as exc:
         where = "%s %s" % (method, redact_url(url))
-        raise HttpError("%s: foreign-user: %s" % (where, exc), url=redact_url(url), kind="foreign-user") from None
+        owner = getattr(exc, "owner", None)
+        why = str(getattr(owner, "reason", None) or getattr(owner, "kind", None) or getattr(exc, "code", "") or "unknown")
+        reason = _po.TABLE_RESTRICTED if why.startswith(_po.TABLE_RESTRICTED) else why.split(":", 1)[0]
+        raise HttpError("%s: foreign-user: %s" % (where, exc), url=redact_url(url), kind="foreign-user", reason=reason) from None
     except (OSError, http.client.HTTPException) as exc:
         if watchdog.fired:
             raise TimeoutError("the answer did not arrive within the deadline")

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

@@ -67,6 +67,20 @@ class HubError(Exception):
         return "HubError(%r, %r)" % (self.code, self.message)
 
 
+def listener_refusal(exc: Any) -> HubError:
+    """The HubError for a hub port the peer-owner check refused (DEC-0154 HA-2): code `foreign-user`, the pinned
+    contract's state name, with the owner's reason in the sentence and in `data.reason` (FAA-272): `table-restricted`
+    when this process's socket table hides other processes' sockets, which never clears, so it is not retryable;
+    otherwise the owner's kind or the check's reason (`another-account`, `no-row`), retryable as before."""
+    owner = getattr(exc, "owner", None)
+    why = (getattr(owner, "reason", None) or getattr(owner, "kind", None) or getattr(exc, "code", None) or "unknown")
+    reason = _po.TABLE_RESTRICTED if str(why).startswith(_po.TABLE_RESTRICTED) else str(why).split(":", 1)[0]
+    kind = getattr(owner, "kind", None)
+    shown = "%s: %s" % (kind, owner.reason) if kind and getattr(owner, "reason", None) else str(kind or why)
+    return HubError("foreign-user", "The hub's port is not held by this OS account's process (%s); nothing was sent." % shown,
+                    reason != _po.TABLE_RESTRICTED, {"reason": reason})
+
+
 # --- where Fabric is --------------------------------------------------------------------------------------------
 
 def fabric_root(platform: str = sys.platform, env: Optional[Dict[str, str]] = None) -> Path:
@@ -233,8 +247,7 @@ def post_mcp(origin: str, body: Dict[str, Any], bearer: str, session: Optional[s
         raw = resp.read(4 * 1024 * 1024)
         got = {k.lower(): v for k, v in resp.getheaders()}
     except _po.ListenerRefused as exc:
-        raise HubError("foreign-user", "The hub's port is not held by this OS account's process (%s); nothing was sent."
-                       % (exc.owner.kind if exc.owner else exc.code), True) from None
+        raise listener_refusal(exc) from None
     except (OSError, http.client.HTTPException) as exc:
         raise HubError("hub-unavailable", "Fabric's hub did not answer (%s)." % exc.__class__.__name__, True) from None
     finally:

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

@@ -825,7 +825,7 @@ class McpToolServer:
             gated = self._gate_action(action, "fabric.job.get", {"id": job_id, "inputResponses": {key: value}}, None, None,
                                       headers, tier, meta, caller, mandate)
             if not gated["ok"]:
-                return gated
+                return dict(gated, capability=private.get("capability"))  # the one read names the fault (FAA-186)
             records[key] = gated["record"]
         return {"ok": True, "records": records}
 
@@ -933,7 +933,7 @@ class McpToolServer:
                 if not inputs["ok"] and "invalid" in inputs:
                     return self._error(rid, -32602, inputs["invalid"])
                 if not inputs["ok"]:
-                    stored = self.jobs.private(str(arguments.get("id", ""))).get("capability")
+                    stored = inputs.get("capability")  # read once, by _gate_inputs (FAA-186)
                     self._fault(stored if isinstance(stored, str) else name, inputs)  # as the start heard it (FAA-179)
                     import fabric_delegation as _fd  # noqa: E402 - DL-19
                     return {"jsonrpc": "2.0", "id": rid, "result": _fd.refusal_tool_result(inputs["refusal"], traceparent=span)}

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}