@passioncode-ai/fabric-agent-adapter 0.39.1 → 0.40.0

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

@@ -120,8 +120,9 @@ of `[A-Za-z0-9][A-Za-z0-9_-]{0,127}`. Absent is `personal`; `null` is not absent
   `publisherKeys` pins. A key no scope names keeps DEC-0051's meaning, trusted in any context.
 - **Update a copied kit before a revision carries `publisherScopes`.** A service runs the copy of the kit it was built
   with; a copy older than 0.39.0 does not read `publisherScopes`, so it trusts a partner's key in every context and
-  finds no rule broken. A service that applies the estate record updates its copy of `fabric_estate.py` /
-  `fabric-estate.mjs` to 0.39.0 or later first.
+  finds no rule broken. A service that applies the estate record updates its copy first:
+  `fabric_kit.py install <dir> --module fabric_estate` (or `--lang node --module fabric-estate`). Since 0.40.0 the
+  estate reader imports the kit's core modules, so the one file alone no longer loads ([kit modules](kit-modules.md)).
 
 Every rule is total on hostile JSON, as the contract's are: an `instancePath` names an item by its index as written (a
 non-object before it does not shift it), and a value whose own `toString` member is data is shown as its JSON. Both kits

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

@@ -0,0 +1,128 @@
+# The service kit: modules, layers and installing them
+
+Since 0.40.0 (FAA-65) the kit is a set of small modules in two languages, not two large files. `scripts/kit.json`
+lists every module in dependency order, per language, with the kit modules it imports and its sha256; `history` keeps
+the digests of every release since 0.8.0, so a copy in a service can be told apart. `scripts/fabric_kit.py` installs a
+module with exactly what it needs and reports a copy's state. Tests: `test/test_fabric_kit.py`,
+`test/test_kit_api.py`, `test/kit-api.test.mjs`.
+
+## Contents
+
+- [Install, status, build](#install-status-build)
+- [The layers](#the-layers)
+- [What 0.39 code keeps](#what-039-code-keeps)
+- [Dates and times](#dates-and-times)
+- [Adding or changing a module](#adding-or-changing-a-module)
+
+## Install, status, build
+
+```bash
+K=<adapter>/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts
+python3 $K/fabric_kit.py install <service-dir>                      # fabric_service and its closure (Python)
+python3 $K/fabric_kit.py install <service-dir> --module fabric_service --module fabric_interop --module fabric_board
+                                                                    # what sample_service.py imports
+python3 $K/fabric_kit.py install <service-dir> --lang node          # fabric-service.mjs and its closure
+python3 $K/fabric_kit.py install <service-dir> --module fabric_openrouter --module fabric_board
+python3 $K/fabric_kit.py install <service-dir> --all --dry-run      # every module, nothing written
+python3 $K/fabric_kit.py status <service-dir> [--json]              # current, older (the release), modified, missing
+python3 $K/fabric_kit.py build [--check]                            # maintainers: refresh kit.json from the sources
+```
+
+- `install` copies the closure of the named modules and nothing else. It refuses to overwrite a file it does not
+  recognise (`modified`: someone edited the copy) unless `--force`, and says which.
+- `status` names each kit file in the folder as `current`, `older` with the release it came from, or `modified`, and
+  prints `missing <file>, which <file> imports` for every module the folder lacks, read from what each copy itself
+  imports and followed through the modules it would install: that copy would fail when that code path runs. A folder
+  holding only the 0.40.0 `fabric_service.py` gets one line for each of the 16 modules it needs; a 0.39.1 copy is
+  asked only for what it imports (`test_an_older_copy_is_judged_by_its_own_imports`).
+- Exit codes: 0 done or every copy current, 1 a problem (a copy missing, `older` or `modified`, no kit module in the
+  folder at all, an install refused), 2 usage (an unknown `--module` included).
+- Every kit module puts its own folder on `sys.path` before it imports a sibling, so a service that loads a kit file
+  by its path from another working directory gets its siblings too (`test_every_module_loads_by_path_from_any_folder`).
+- `build --check` is what CI runs: `kit.json` must be what the sources say.
+
+## The layers
+
+A module imports only modules listed before it in `kit.json`, so the kit has no import cycle and no upward import
+(`test_the_order_is_a_layering`; a planted cycle is caught). Python name first, the Node twin is the same name with
+`-` for `_` and `.mjs`. No module is over 1000 lines (`test_no_module_over_the_line_ceiling`).
+
+| Layer | Module | What it holds |
+|---|---|---|
+| L0 | `fabric_jsvalue` | JavaScript's view of JSON values: numbers, strings, equality, `jcs`, `show`; defined once for the kit |
+| L0 | `fabric_time` | strict RFC 3339, UTC days, formatting, day windows, the clock ([dates](#dates-and-times)) |
+| L0 | `fabric_identifiers` | identifier equality by normal form (DEC-0076) |
+| L0 | `fabric_secrets` | the contract's one credential detector (DEC-0044) |
+| L1 | `fabric_crypto` | Ed25519 and P-256 verification, base64url, sha256: what the verifiers need and nothing more |
+| L2 | `fabric_estate` | `estate-record/1` revisions and their rules (DEC-0055) |
+| L2 | `fabric_delegation` | the callee's side of `fabric-delegation/0.1` (DEC-0039) |
+| L2 | `fabric_share` | share grants and registrations (DEC-0086) |
+| L2 | `fabric_ceremonies` | the headless join token (DEC-0084) |
+| L2 | `fabric_package` | `fabric-package/1`: pack, sign, verify (DEC-0050, DEC-0051) |
+| L3 | `fabric_base` | the protocol name, `ServiceError`, small shared helpers |
+| L3 | `fabric_platform` | Windows: named pipes, owner-only files (DEC-0032) |
+| L3 | `fabric_paths` | the services directory, a service's folders, atomic and private writes |
+| L3 | `fabric_protocols` | protocol revisions (DEC-0067) and feed data (DEC-0070) |
+| L3 | `fabric_lock` | the instance lock and the supervisor marker (LC-01, DEC-0057) |
+| L3 | `fabric_usage` | usage receipts, the ledger, the usage report, attribution, spending limits ([usage](usage.md)) |
+| L3 | `fabric_backups` | settings backups (DEC-0025) |
+| L3 | `fabric_descriptor` | the descriptor, peers, app descriptors, the well-known document |
+| L3 | `fabric_auth` | the token, the network guard, login codes |
+| L3 | `fabric_events` | events, paging, the JSONL event log (DEC-0029) |
+| L3 | `fabric_logs` | rotating logs, the stop signal and the drain (LC-12) |
+| L3 | `fabric_supervisors` | launchd, systemd user units, Task Scheduler (DEC-0032, LC-14) |
+| L3 | `fabric_service` | the facade: every name 0.39.1 exported, re-exported from the modules above |
+| L3 | `fabric_profiles` | runner and model profiles ([profiles](profiles.md)) |
+| L3 | `fabric_interop` | `fabric-interop/0.1`: jobs, envelopes, MCP tools ([interop](interop.md)) |
+| L4 | `fabric_hub` | the Fabric hub's door (`fabric-hub/0.1`) |
+| L4 | `fabric_board_shapes` | the project board's wire: constants, refusal codes, shapes |
+| L4 | `fabric_board_session` | the board responder: a session, the checkpoint, the fenced request |
+| L4 | `fabric_board_fixture` | the scripted board the probe runs a responder against |
+| L4 | `fabric_board` | the facade of the board connector ([board](board.md)) |
+| L4 | `fabric_http` | outbound HTTP: deadline, bounded retries, `Retry-After`, size cap ([connectors](connectors.md)) |
+| L4 | `fabric_openrouter` | OpenRouter chat: own key, spend ceiling, receipts, fallback ([connectors](connectors.md)) |
+
+Beside the kit, not in `kit.json`: the probe (`check_service.py`, `check_service_rules.py`), the sample
+(`sample_service.py`, `sample-remote-service.mjs`), `fabric_kit.py` itself and the dashboard tools. Recipes built on
+the kit live in `../recipes/` ([the support agent](../recipes/support-agent/README.md)).
+
+## What 0.39 code keeps
+
+`import fabric_service as fs` and `import ... from './fabric-service.mjs'` keep working: the facades re-export every
+public name 0.39.1 had, in both languages (the snapshot is `test/fixtures/kit-api/kit-api-0.39.1.json`; a missing
+name fails `test_kit_api`), and the Python facade the private names other code reached through it (`_number`,
+`_DAY_MS`, `_utc_date_ms` from the core). `fabric_board` and `fabric-board.mjs` are
+facades the same way. What changed for a service that copies the kit: `fabric_service.py` alone is no longer enough;
+install with `fabric_kit.py install` and `status` names what is missing. A test or service that replaced a function
+by assigning it on the facade (`fabric_service.X = ...`) no longer changes what the kit does: the code reads its own
+module's name, so patch the module that defines it (`fabric_lock.X`, `fabric_session_env.X`). A service that imported a module-private
+helper (`_x`) of the Node twin should import it from its module now.
+
+## Dates and times
+
+`fabric_time` / `fabric-time.mjs` is the kit's one reading of dates, on the cases both twins test
+(`test/fixtures/kit-time-cases.json`). Anything unreadable is NaN, never an exception, so a check compares it and
+reports a finding.
+
+| Python | Node | What |
+|---|---|---|
+| `parse_rfc3339_ms(text)` | `parseRfc3339Ms(text)` | strict RFC 3339: a `T`, an offset and a day that exists; no space, no leap second; milliseconds or NaN |
+| `utc_date_ms(text)` | `utcDateMs(text)` | a `YYYY-MM-DD` that exists, as midnight UTC in milliseconds, or NaN |
+| `utc_day(ms)` | `utcDay(ms)` | the UTC calendar day of an instant (NaN or Infinity raise) |
+| `format_rfc3339(ms)` | `formatRfc3339(ms)` | `2026-10-21T09:00:00.000Z`, which parses back to the same value |
+| `day_window(today_ms, days)` | `dayWindow(todayMs, days)` | the last N UTC days ending with today's, oldest first (a usage report's 31) |
+| `clock_ms(at)` | `clockMs(at)` | a verifier's clock (an aware `datetime` / a `Date`, or epoch seconds) in milliseconds |
+| `now_ms(clock)` | `nowMs(clock)` | now in milliseconds; `clock` returns seconds in Python (`time.time`), milliseconds in Node (`Date.now`) |
+| `DAY_MS` | `DAY_MS` | 86 400 000 |
+
+`fabric_estate.estate_time` is `parse_rfc3339_ms` under its older name.
+
+## Adding or changing a module
+
+1. Put it in the lowest layer whose modules it needs; import only modules listed before it.
+2. Write the Node twin with the same public names in camelCase, and shared cases under `test/fixtures/` that both
+   test files read.
+3. Add it to `kit.json` (module, file, layer) and run `fabric_kit.py build`; add it to the table above
+   (`test_every_kit_module_is_documented`).
+4. A value or helper the core already has is imported, never redefined (`test_the_core_is_defined_once`).
+5. Stay under 1000 lines; split by responsibility, keeping a facade when callers already import the old name.

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

@@ -29,6 +29,8 @@ ledger.record(receipt)                     # fs.JsonlUsageLedger(data / "usage.j
 ledger.record(k.makeUsageReceipt('openrouter', model, { inputTokens, outputTokens, costUsd: usage.cost ?? null }));
 ```
 
+- **OpenRouter through the kit.** `fabric_openrouter.Client` records these receipts itself, one per answered call,
+  and checks a spend ceiling before every attempt ([connectors](connectors.md)).
 - **The provider's own numbers.** Take tokens from the response's usage block, not from a local
   estimate. The cost is `provider` when the provider reported the charge (OpenRouter `usage.cost`,
   a billing API) and `price-list` when you computed it from a published price list.

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

@@ -57,74 +57,16 @@ import fabric_interop as fi  # noqa: E402
 Result = Dict[str, str]
 
 
-
-def plist_problems(plist: dict, label: object, token: object = None) -> list:
-    """What makes a service's launchd job unfit to stay up: identity, restart, secrets."""
-    problems = []
-    if plist.get("Label") != label:
-        problems.append("Label %r" % plist.get("Label"))
-    if plist.get("RunAtLoad") is not True:
-        problems.append("RunAtLoad is not true")
-    if plist.get("KeepAlive") is not True:
-        problems.append("KeepAlive is %r, not true" % plist.get("KeepAlive"))
-    for key, value in (plist.get("EnvironmentVariables") or {}).items():
-        if re.search(r"(TOKEN|SECRET|PASSWORD|KEY)$", key) and not key.endswith("_FILE"):
-            problems.append("secret-like variable %s in the plist" % key)
-        if token and token in str(value):
-            problems.append("the service token itself is in the plist")
-    return problems
-
-
-def marker_problem(plist: dict) -> Optional[str]:
-    """What is wrong with the job's supervisor marker (DEC-0057; FAA-05), read the way the copy it starts reads it.
-
-    Without ``FABRIC_SERVICE_SUPERVISOR=launchd`` (or ``--fabric-supervisor launchd``) a copy that finds the
-    lock held exits 75 at once, and KeepAlive starts it again every ThrottleInterval."""
-    env = plist.get("EnvironmentVariables")
-    env = {str(k): str(v) for k, v in env.items()} if isinstance(env, dict) else {}
-    argv = plist.get("ProgramArguments")
-    argv = [str(a) for a in argv] if isinstance(argv, list) else []
-    marker = fs.supervisor_marker(env, argv)
-    if marker["kind"] == "supervised" and marker["manager"] == "launchd":
-        return None
-    fix = ("a copy that finds the lock held exits 75 at once and KeepAlive respawns it every ThrottleInterval; "
-           "regenerate the plist with launchd_plist / launchdPlist and reinstall")
-    if marker["kind"] == "conflict":
-        return "%s: %s" % (fs.marker_conflict_message(marker), fix)
-    if marker["kind"] == "supervised":
-        return "the marker names %s, not launchd: %s" % (marker["manager"], fix)
-    if marker.get("unreadable") is not None:
-        return "the marker %r names no supervisor: %s" % (marker["unreadable"], fix)
-    return "no %s=launchd: %s" % (fs.SUPERVISOR_ENV, fix)
-
-
-def priority_problems(plist: dict) -> list:
-    """A service that answers hosts and agents must not be scheduled as background work."""
-    out = []
-    if plist.get("ProcessType", "Standard") in ("Background", "Adaptive"):
-        out.append("ProcessType is %s" % plist.get("ProcessType"))
-    if isinstance(plist.get("Nice"), int) and plist["Nice"] > 0:
-        out.append("Nice is %d" % plist["Nice"])
-    if plist.get("LowPriorityIO") is True or plist.get("LowPriorityBackgroundIO") is True:
-        out.append("low-priority I/O")
-    return out
-
-
-# A platform router (Heroku, Fly, Render, a CDN) routes by Host, so a request naming a foreign
-# Host never reaches an online service: the router itself answers, typically 404 or 421. That is
-# still a refusal — the service disclosed nothing — so for a remote placement the host check
-# accepts it, as long as the body is not the well-known document. Every other guard request names
-# the right Host, reaches the service, and must be the service's own 403.
-PLATFORM_HOST_REFUSALS = (400, 404, 421)
-
-
-def guard_verdict(rule: str, remote: bool, status: int, body: bytes) -> Tuple[str, str]:
-    if status == 403:
-        return "PASS", "HTTP 403"
-    disclosed = b"fabric-service/" in (body or b"")
-    if rule == "network.host-check" and remote and status in PLATFORM_HOST_REFUSALS and not disclosed:
-        return "PASS", "HTTP %d from the platform router: a foreign Host never reaches the service" % status
-    return "FAIL", "HTTP %d%s" % (status, ", and the body is the well-known document" if disclosed else "")
+from check_service_rules import PLATFORM_HOST_REFUSALS  # noqa: E402,F401 - moved (FAA-65)
+from check_service_rules import plist_problems  # noqa: E402,F401 - moved (FAA-65)
+from check_service_rules import marker_problem  # noqa: E402,F401 - moved (FAA-65)
+from check_service_rules import priority_problems  # noqa: E402,F401 - moved (FAA-65)
+from check_service_rules import guard_verdict  # noqa: E402,F401 - moved (FAA-65)
+from check_service_rules import board_responder_verdict  # noqa: E402,F401 - moved (FAA-65)
+from check_service_rules import session_lifetime_problem  # noqa: E402,F401 - moved (FAA-65)
+from check_service_rules import _semver  # noqa: E402,F401 - moved (FAA-65)
+from check_service_rules import usage_problems  # noqa: E402,F401 - moved (FAA-65)
+from check_service_rules import same_repository  # noqa: E402,F401 - moved (FAA-65)
 
 
 class _PinnedHTTPS(http.client.HTTPSConnection):
@@ -839,121 +781,6 @@ class Probe:
         return self.results
 
 
-def board_responder_verdict(wk: Any, kit: Optional[str] = None) -> Tuple[str, str]:
-    """board.responder: NOT_RUN when the well-known document declares no fabric-project-comms revision; FAIL when it
-    declares one this kit does not read or the kit's fixture conversation finds a problem; PASS otherwise. `kit` is the
-    service's own copy (a .py or .mjs path); by default the kit beside this probe."""
-    protocols = wk.get("protocols") if isinstance(wk, dict) else None
-    declared = [p for p in protocols if isinstance(p, str) and p.startswith("fabric-project-comms/")] if isinstance(protocols, list) else []
-    if not declared:
-        return "NOT_RUN", "the service declares no board participation (no fabric-project-comms revision in protocols)"
-    accepted = fs.accepted_revisions("fabric-project-comms")
-    unread = [p for p in declared if "error" in fs.negotiate_revision(p, accepted)]
-    if unread:
-        return "FAIL", "declares %s, which this kit does not read (it reads %s)" % (", ".join(unread), ", ".join(accepted))
-    try:
-        if kit and kit.endswith(".mjs"):
-            if not shutil.which("node"):
-                return "NOT_RUN", "node is not installed to run %s's fixture conversation" % kit
-            url = Path(kit).resolve().as_uri()
-            out = subprocess.run(["node", "--input-type=module", "-e",
-                                  "import(process.env.FABRIC_BOARD_KIT).then(async (m) => console.log(JSON.stringify(await m.selfCheck())))"],
-                                 env=dict(os.environ, FABRIC_BOARD_KIT=url), capture_output=True, text=True, timeout=60)
-            problems = json.loads(out.stdout.strip().splitlines()[-1]) if out.returncode == 0 and out.stdout.strip() else ["the Node kit did not run: %s" % out.stderr.strip()[:200]]
-        else:
-            import importlib.util
-            path = Path(kit) if kit else Path(__file__).resolve().parent / "fabric_board.py"
-            spec = importlib.util.spec_from_file_location("fabric_board_under_test", str(path))
-            module = importlib.util.module_from_spec(spec)
-            sys.path.insert(0, str(path.resolve().parent))
-            spec.loader.exec_module(module)  # type: ignore[union-attr]
-            problems = module.self_check()
-    except Exception as exc:  # noqa: BLE001 - a kit that cannot run its conversation fails the rule
-        return "FAIL", "the kit's fixture conversation did not run: %s" % exc.__class__.__name__
-    if problems:
-        return "FAIL", "; ".join(problems)
-    return "PASS", "declares %s; the kit%s answers the fixture conversation (whole, fenced, no epoch)" % (
-        ", ".join(declared), " at %s" % kit if kit else " beside this probe")
-
-
-def session_lifetime_problem(set_cookie: str, now: Optional[float] = None) -> Optional[str]:
-    """DEC-0039: a session cookie set at sign-in lives at most 7 days. Max-Age wins over Expires (RFC 6265
-    §5.3); a cookie with neither ends with the browser session. None when it is within the bound."""
-    attrs = {}
-    for part in set_cookie.split(";")[1:]:
-        name, _, value = part.strip().partition("=")
-        attrs[name.strip().lower()] = value.strip()
-    bound = fs.OPERATOR_SESSION_MAX_SECONDS
-    if "max-age" in attrs:
-        if not re.fullmatch(r"-?\d+", attrs["max-age"]):
-            return "the session cookie's Max-Age %r is not a number" % attrs["max-age"]
-        if int(attrs["max-age"]) > bound:
-            return "the session cookie's Max-Age %s outlives 7 days (%d s, DEC-0039)" % (attrs["max-age"], bound)
-        return None
-    if "expires" in attrs:
-        try:
-            at = email.utils.parsedate_to_datetime(attrs["expires"]).timestamp()
-        except (TypeError, ValueError, IndexError, OverflowError):
-            return "the session cookie's Expires %r is not a date" % attrs["expires"]
-        if at - (time.time() if now is None else now) > bound:
-            return "the session cookie's Expires %s outlives 7 days (DEC-0039)" % attrs["expires"]
-    return None
-
-
-def _semver(text: str) -> Tuple[int, int, int]:
-    m = re.match(r"^(\d+)\.(\d+)\.(\d+)", text or "")
-    return (int(m.group(1)), int(m.group(2)), int(m.group(3))) if m else (0, 0, 0)
-
-
-def usage_problems(report: Any, service_id: str, instance: str) -> List[str]:
-    """What makes this not a DEC-0021 usage report of the service: shape, identity and the sums of
-    FAC-SEM-025. An unknown cost must be null; a day's totals are the sums of its models."""
-    if not isinstance(report, dict):
-        return ["not an object"]
-    out: List[str] = []
-    if report.get("protocol") != fs.PROTOCOL:
-        out.append("protocol is %r" % report.get("protocol"))
-    if report.get("service") != {"id": service_id, "instance": instance}:
-        out.append("reports for %r, not %s.%s" % (report.get("service"), service_id, instance))
-    if report.get("currency") != "USD":
-        out.append("currency is not USD")
-    days = report.get("days")
-    if not isinstance(days, list) or len(days) > fs.USAGE_DAYS:
-        return out + ["days is not a list of at most 31"]
-    # The arithmetic of FAC-SEM-025 is the kit's `usage_findings`, the contract's `usageRules` held to its vectors: one
-    # implementation, so the probe never disagrees with the kit and never throws on a count that is not a number.
-    for i, day in enumerate(days):
-        if not isinstance(day, dict):
-            out.append("days[%d]: not an object" % i)
-            continue
-        if not isinstance(day.get("byModel"), list):
-            out.append("days[%d]: byModel missing" % i)
-            continue
-        for row, at in [(day, "days[%d]" % i)] + [(m, "days[%d].byModel[%d]" % (i, j)) for j, m in enumerate(day["byModel"]) if isinstance(m, dict)]:
-            cost = row.get("costUsd")
-            if cost is not None and (isinstance(cost, bool) or not isinstance(cost, (int, float)) or cost < 0):
-                out.append("%s: costUsd is not a non-negative number" % at)
-        for j, m in enumerate(day["byModel"]):
-            # DEC-0046, DEC-0061: a row's route is a login in its vendor's runner, an issued key, or the platform's
-            # own metered models (a listing in the cloud).
-            if isinstance(m, dict) and "route" in m and m["route"] not in fs.USAGE_ROUTES:
-                out.append("days[%d].byModel[%d]: route %r is not subscription, key or platform-metered" % (i, j, m["route"]))
-    for finding in fs.usage_findings(report):
-        out.append("%s: %s" % (finding["instancePath"] or "/", finding["message"]))
-    return out
-
-
-def same_repository(a: str, b: str) -> bool:
-    """git@github.com:o/r.git, https://github.com/o/r and github.com/o/r are one repository."""
-    def norm(u: str) -> str:
-        u = u.strip().lower()
-        u = re.sub(r"^git@([^:]+):", r"\1/", u)
-        u = re.sub(r"^[a-z+]+://", "", u)
-        u = re.sub(r"^[^@/]+@", "", u)
-        return re.sub(r"\.git$", "", u).rstrip("/")
-    return bool(a and b) and norm(a) == norm(b)
-
-
 def locate(target: Optional[str], descriptor: Optional[str], services_dir: Path) -> Path:
     if descriptor:
         return Path(descriptor).expanduser()

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

@@ -0,0 +1,204 @@
+"""The probe's rules that read one thing and need no running service (FAA-65): a plist's marker and priority, the
+network guard's verdict, the board responder's fixture conversation, a session cookie's lifetime, a usage report, and
+whether two repository URLs name one repository. ``check_service.py`` runs them against a live service.
+Standard library only, Python 3.9+."""
+from __future__ import annotations
+
+import email.utils
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import fabric_service as fs  # noqa: E402 - beside this file
+
+
+def plist_problems(plist: dict, label: object, token: object = None) -> list:
+    """What makes a service's launchd job unfit to stay up: identity, restart, secrets."""
+    problems = []
+    if plist.get("Label") != label:
+        problems.append("Label %r" % plist.get("Label"))
+    if plist.get("RunAtLoad") is not True:
+        problems.append("RunAtLoad is not true")
+    if plist.get("KeepAlive") is not True:
+        problems.append("KeepAlive is %r, not true" % plist.get("KeepAlive"))
+    for key, value in (plist.get("EnvironmentVariables") or {}).items():
+        if re.search(r"(TOKEN|SECRET|PASSWORD|KEY)$", key) and not key.endswith("_FILE"):
+            problems.append("secret-like variable %s in the plist" % key)
+        if token and token in str(value):
+            problems.append("the service token itself is in the plist")
+    return problems
+
+
+def marker_problem(plist: dict) -> Optional[str]:
+    """What is wrong with the job's supervisor marker (DEC-0057; FAA-05), read the way the copy it starts reads it.
+
+    Without ``FABRIC_SERVICE_SUPERVISOR=launchd`` (or ``--fabric-supervisor launchd``) a copy that finds the
+    lock held exits 75 at once, and KeepAlive starts it again every ThrottleInterval."""
+    env = plist.get("EnvironmentVariables")
+    env = {str(k): str(v) for k, v in env.items()} if isinstance(env, dict) else {}
+    argv = plist.get("ProgramArguments")
+    argv = [str(a) for a in argv] if isinstance(argv, list) else []
+    marker = fs.supervisor_marker(env, argv)
+    if marker["kind"] == "supervised" and marker["manager"] == "launchd":
+        return None
+    fix = ("a copy that finds the lock held exits 75 at once and KeepAlive respawns it every ThrottleInterval; "
+           "regenerate the plist with launchd_plist / launchdPlist and reinstall")
+    if marker["kind"] == "conflict":
+        return "%s: %s" % (fs.marker_conflict_message(marker), fix)
+    if marker["kind"] == "supervised":
+        return "the marker names %s, not launchd: %s" % (marker["manager"], fix)
+    if marker.get("unreadable") is not None:
+        return "the marker %r names no supervisor: %s" % (marker["unreadable"], fix)
+    return "no %s=launchd: %s" % (fs.SUPERVISOR_ENV, fix)
+
+
+def priority_problems(plist: dict) -> list:
+    """A service that answers hosts and agents must not be scheduled as background work."""
+    out = []
+    if plist.get("ProcessType", "Standard") in ("Background", "Adaptive"):
+        out.append("ProcessType is %s" % plist.get("ProcessType"))
+    if isinstance(plist.get("Nice"), int) and plist["Nice"] > 0:
+        out.append("Nice is %d" % plist["Nice"])
+    if plist.get("LowPriorityIO") is True or plist.get("LowPriorityBackgroundIO") is True:
+        out.append("low-priority I/O")
+    return out
+
+
+# A platform router (Heroku, Fly, Render, a CDN) routes by Host, so a request naming a foreign
+# Host never reaches an online service: the router itself answers, typically 404 or 421. That is
+# still a refusal — the service disclosed nothing — so for a remote placement the host check
+# accepts it, as long as the body is not the well-known document. Every other guard request names
+# the right Host, reaches the service, and must be the service's own 403.
+PLATFORM_HOST_REFUSALS = (400, 404, 421)
+
+
+def guard_verdict(rule: str, remote: bool, status: int, body: bytes) -> Tuple[str, str]:
+    if status == 403:
+        return "PASS", "HTTP 403"
+    disclosed = b"fabric-service/" in (body or b"")
+    if rule == "network.host-check" and remote and status in PLATFORM_HOST_REFUSALS and not disclosed:
+        return "PASS", "HTTP %d from the platform router: a foreign Host never reaches the service" % status
+    return "FAIL", "HTTP %d%s" % (status, ", and the body is the well-known document" if disclosed else "")
+
+
+def board_responder_verdict(wk: Any, kit: Optional[str] = None) -> Tuple[str, str]:
+    """board.responder: NOT_RUN when the well-known document declares no fabric-project-comms revision; FAIL when it
+    declares one this kit does not read or the kit's fixture conversation finds a problem; PASS otherwise. `kit` is the
+    service's own copy (a .py or .mjs path); by default the kit beside this probe."""
+    protocols = wk.get("protocols") if isinstance(wk, dict) else None
+    declared = [p for p in protocols if isinstance(p, str) and p.startswith("fabric-project-comms/")] if isinstance(protocols, list) else []
+    if not declared:
+        return "NOT_RUN", "the service declares no board participation (no fabric-project-comms revision in protocols)"
+    accepted = fs.accepted_revisions("fabric-project-comms")
+    unread = [p for p in declared if "error" in fs.negotiate_revision(p, accepted)]
+    if unread:
+        return "FAIL", "declares %s, which this kit does not read (it reads %s)" % (", ".join(unread), ", ".join(accepted))
+    try:
+        if kit and kit.endswith(".mjs"):
+            if not shutil.which("node"):
+                return "NOT_RUN", "node is not installed to run %s's fixture conversation" % kit
+            url = Path(kit).resolve().as_uri()
+            out = subprocess.run(["node", "--input-type=module", "-e",
+                                  "import(process.env.FABRIC_BOARD_KIT).then(async (m) => console.log(JSON.stringify(await m.selfCheck())))"],
+                                 env=dict(os.environ, FABRIC_BOARD_KIT=url), capture_output=True, text=True, timeout=60)
+            problems = json.loads(out.stdout.strip().splitlines()[-1]) if out.returncode == 0 and out.stdout.strip() else ["the Node kit did not run: %s" % out.stderr.strip()[:200]]
+        else:
+            # A clean interpreter: the kit is several modules (FAA-65), and modules this probe already imported from
+            # beside it would stand in for the copy under test.
+            path = Path(kit) if kit else Path(__file__).resolve().parent / "fabric_board.py"
+            code = ("import json, sys; sys.path.insert(0, sys.argv[1]); import %s as board; "
+                    "print(json.dumps(board.self_check()))" % path.stem)
+            out = subprocess.run([sys.executable, "-E", "-s", "-c", code, str(path.resolve().parent)], capture_output=True,
+                                 text=True, timeout=60, cwd=str(path.resolve().parent))
+            problems = json.loads(out.stdout.strip().splitlines()[-1]) if out.returncode == 0 and out.stdout.strip() else ["the kit did not run: %s" % out.stderr.strip()[-200:]]
+    except Exception as exc:  # noqa: BLE001 - a kit that cannot run its conversation fails the rule
+        return "FAIL", "the kit's fixture conversation did not run: %s" % exc.__class__.__name__
+    if problems:
+        return "FAIL", "; ".join(problems)
+    return "PASS", "declares %s; the kit%s answers the fixture conversation (whole, fenced, no epoch)" % (
+        ", ".join(declared), " at %s" % kit if kit else " beside this probe")
+
+
+def session_lifetime_problem(set_cookie: str, now: Optional[float] = None) -> Optional[str]:
+    """DEC-0039: a session cookie set at sign-in lives at most 7 days. Max-Age wins over Expires (RFC 6265
+    §5.3); a cookie with neither ends with the browser session. None when it is within the bound."""
+    attrs = {}
+    for part in set_cookie.split(";")[1:]:
+        name, _, value = part.strip().partition("=")
+        attrs[name.strip().lower()] = value.strip()
+    bound = fs.OPERATOR_SESSION_MAX_SECONDS
+    if "max-age" in attrs:
+        if not re.fullmatch(r"-?\d+", attrs["max-age"]):
+            return "the session cookie's Max-Age %r is not a number" % attrs["max-age"]
+        if int(attrs["max-age"]) > bound:
+            return "the session cookie's Max-Age %s outlives 7 days (%d s, DEC-0039)" % (attrs["max-age"], bound)
+        return None
+    if "expires" in attrs:
+        try:
+            at = email.utils.parsedate_to_datetime(attrs["expires"]).timestamp()
+        except (TypeError, ValueError, IndexError, OverflowError):
+            return "the session cookie's Expires %r is not a date" % attrs["expires"]
+        if at - (time.time() if now is None else now) > bound:
+            return "the session cookie's Expires %s outlives 7 days (DEC-0039)" % attrs["expires"]
+    return None
+
+
+def _semver(text: str) -> Tuple[int, int, int]:
+    m = re.match(r"^(\d+)\.(\d+)\.(\d+)", text or "")
+    return (int(m.group(1)), int(m.group(2)), int(m.group(3))) if m else (0, 0, 0)
+
+
+def usage_problems(report: Any, service_id: str, instance: str) -> List[str]:
+    """What makes this not a DEC-0021 usage report of the service: shape, identity and the sums of
+    FAC-SEM-025. An unknown cost must be null; a day's totals are the sums of its models."""
+    if not isinstance(report, dict):
+        return ["not an object"]
+    out: List[str] = []
+    if report.get("protocol") != fs.PROTOCOL:
+        out.append("protocol is %r" % report.get("protocol"))
+    if report.get("service") != {"id": service_id, "instance": instance}:
+        out.append("reports for %r, not %s.%s" % (report.get("service"), service_id, instance))
+    if report.get("currency") != "USD":
+        out.append("currency is not USD")
+    days = report.get("days")
+    if not isinstance(days, list) or len(days) > fs.USAGE_DAYS:
+        return out + ["days is not a list of at most 31"]
+    # The arithmetic of FAC-SEM-025 is the kit's `usage_findings`, the contract's `usageRules` held to its vectors: one
+    # implementation, so the probe never disagrees with the kit and never throws on a count that is not a number.
+    for i, day in enumerate(days):
+        if not isinstance(day, dict):
+            out.append("days[%d]: not an object" % i)
+            continue
+        if not isinstance(day.get("byModel"), list):
+            out.append("days[%d]: byModel missing" % i)
+            continue
+        for row, at in [(day, "days[%d]" % i)] + [(m, "days[%d].byModel[%d]" % (i, j)) for j, m in enumerate(day["byModel"]) if isinstance(m, dict)]:
+            cost = row.get("costUsd")
+            if cost is not None and (isinstance(cost, bool) or not isinstance(cost, (int, float)) or cost < 0):
+                out.append("%s: costUsd is not a non-negative number" % at)
+        for j, m in enumerate(day["byModel"]):
+            # DEC-0046, DEC-0061: a row's route is a login in its vendor's runner, an issued key, or the platform's
+            # own metered models (a listing in the cloud).
+            if isinstance(m, dict) and "route" in m and m["route"] not in fs.USAGE_ROUTES:
+                out.append("days[%d].byModel[%d]: route %r is not subscription, key or platform-metered" % (i, j, m["route"]))
+    for finding in fs.usage_findings(report):
+        out.append("%s: %s" % (finding["instancePath"] or "/", finding["message"]))
+    return out
+
+
+def same_repository(a: str, b: str) -> bool:
+    """git@github.com:o/r.git, https://github.com/o/r and github.com/o/r are one repository."""
+    def norm(u: str) -> str:
+        u = u.strip().lower()
+        u = re.sub(r"^git@([^:]+):", r"\1/", u)
+        u = re.sub(r"^[a-z+]+://", "", u)
+        u = re.sub(r"^[^@/]+@", "", u)
+        return re.sub(r"\.git$", "", u).rstrip("/")
+    return bool(a and b) and norm(a) == norm(b)