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

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

@@ -18,6 +18,7 @@ Normative source: fabric-agent-contract docs/specification/interop.md (DEC-0016,
 from __future__ import annotations
 
 import base64
+import hashlib
 import json
 from pathlib import Path
 import re
@@ -27,6 +28,7 @@ from typing import Any, Callable, Dict, List, Optional
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 import fabric_service as _fs  # noqa: E402
+from fabric_base import store_lock  # noqa: E402 - one lock per store path (R3)
 
 PROTOCOL = "fabric-interop/0.1"
 EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/interop/0.1"
@@ -49,11 +51,11 @@ JOB_HANDLE_SCHEMA: Dict[str, Any] = {
 }
 TERMINAL = ("completed", "failed", "cancelled")
 
-_TRACEPARENT = re.compile(r"^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$")
-_JOB_ID = re.compile(r"^[A-Za-z0-9._:-]{1,128}$")
-_KEY = re.compile(r"^[A-Za-z0-9_.-]{1,64}$")
+_TRACEPARENT = re.compile(r"^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})\Z")
+_JOB_ID = re.compile(r"^[A-Za-z0-9._:-]{1,128}\Z")
+_KEY = re.compile(r"^[A-Za-z0-9_.-]{1,64}\Z")
 _SECRET_WORDS = re.compile(r"pass(word|phrase)|secret|api[\s_-]?key|access[\s_-]?key|private[\s_-]?key|"
-                           r"(access|auth|bearer|refresh|session)[\s_-]?token|^token$|credential", re.IGNORECASE)
+                           r"(access|auth|bearer|refresh|session)[\s_-]?token|^token\Z|credential", re.IGNORECASE)
 
 
 class InteropError(_fs.ServiceError):
@@ -255,12 +257,7 @@ def _own(value: Any, key: str) -> Any:
     return value.get(key, _ABSENT) if isinstance(value, dict) else _ABSENT
 
 
-def _days_from_civil(year: int, month: int, day: int) -> int:
-    year -= month <= 2
-    era = (year if year >= 0 else year - 399) // 400
-    yoe = year - era * 400
-    doy = (153 * (month + (-3 if month > 2 else 9)) + 2) // 5 + day - 1
-    return era * 146097 + yoe * 365 + yoe // 4 - yoe // 100 + doy - 719468
+from fabric_time import days_from_civil as _days_from_civil  # noqa: E402 - the core's (FAA-65)
 
 
 def utc_time(value: Any) -> Optional[int]:
@@ -370,7 +367,6 @@ def intent_idempotency_key(intent: Any) -> Optional[str]:
     """The idempotency key of an intent {agentId, capability, input, request?}: a UUID of version 8 from the first 16
     bytes of the SHA-256 of its RFC 8785 form. The same intent gives the same key on every resend and machine; None
     for another shape or an input with no RFC 8785 form."""
-    import hashlib
     import fabric_delegation as _fd  # noqa: E402 - beside this file: RFC 8785
     names = ("agentId", "capability", "input", "request")
     if not isinstance(intent, dict) or any(name not in names for name in intent):
@@ -474,6 +470,16 @@ def pause_message(resets_at: Optional[str] = None, text: Optional[str] = None) -
     return message
 
 
+def intent_digest(capability: str, arguments: Any) -> str:
+    """What a key is kept beside (FAA-77): the SHA-256 of the RFC 8785 form of [capability, input], so a key admits
+    only the intent it was first sent with. An input with no RFC 8785 form is refused."""
+    import fabric_delegation as _fd  # noqa: E402 - beside this file: RFC 8785
+    try:
+        return "sha256:" + hashlib.sha256(_fd.jcs([capability, arguments]).encode("utf-8")).hexdigest()
+    except (TypeError, ValueError, RecursionError):
+        raise InteropError("A job's input with an idempotency key needs a JSON form (RFC 8785).") from None
+
+
 def repeated_key_decision(job: Any, now: Any, limit_holds: Optional[bool] = None, approval_granted: bool = False) -> str:
     """The provider's answer to a repeated key: "run" (the same intent runs again, once) or "same" (answer with that job).
     A quota-exhausted job runs again once the limit no longer holds: `limit_holds` False when the provider knows it, else
@@ -530,17 +536,17 @@ def url_request(message: str, url: str) -> Dict[str, Any]:
 
 # --- C3.2 jobs ---------------------------------------------------------------------
 
-class JobStore:
-    """Durable jobs, one private JSON file each under `directory`, written atomically.
+_SURROGATE = re.compile("[\ud800-\udfff]")
 
-    A job id survives a restart of the agent, so fabric.job.get after a restart finds
-    the same job. The file holds the public `job` object exactly as fabric.job.get
-    returns it, and a `private` part (the capability, its input, the trace) that is
-    never returned. The Node kit reads and writes the same format.
-    """
+
+class JobStore:
+    """Durable jobs, one private JSON file each under `directory`, written atomically and under the directory's lock.
+    A job id survives a restart. The file holds the public `job` object exactly as fabric.job.get returns it, and a
+    `private` part (the capability, its input, the trace) that is never returned; the Node kit uses the same format."""
 
     def __init__(self, directory: Path):
         self.dir = Path(directory)
+        self._lock = store_lock(self.dir)
 
     def _path(self, job_id: str) -> Path:
         if not _JOB_ID.match(job_id or ""):
@@ -567,48 +573,76 @@ class JobStore:
                limit_holds: Optional[bool] = None, approval_granted: bool = False) -> Dict[str, Any]:
         """Start a job; returns the handle a job-capable tool puts in structuredContent.
 
-        With `idempotency_key` the key is kept per `caller` (the authenticated caller, DEC-0087): a key that already names
-        a job starts nothing and raises InteropError, unless `repeat` would answer "run" (a limit no longer holds, an
-        approval granted); then the key names the new job."""
-        if idempotency_key is not None:
-            decision = self.repeat(caller, idempotency_key, now if now is not None else _fs.now_iso(),
-                                   limit_holds=limit_holds, approval_granted=approval_granted)
-            if decision["decision"] == "same":
-                raise InteropError("Key %s already names job %s; answer with that job (JobStore.repeat)." % (idempotency_key, decision["job"]["id"]))
-        job_id = "job_" + secrets.token_hex(12)
-        job: Dict[str, Any] = {"id": job_id, "status": "working"}
-        if poll_interval_ms:
-            job["pollIntervalMs"] = int(poll_interval_ms)
-        private: Dict[str, Any] = {"capability": capability, "input": arguments,
-                                   "traceparent": traceparent if parse_traceparent(traceparent) else None}
-        if delegation:  # DEC-0039: who started it; only they read, cancel or answer it
-            private["delegation"] = {"principal": delegation.get("principal"), "caller": delegation.get("caller")}
-        self._save({"job": job, "private": private})
-        if idempotency_key is not None:
-            _fs.atomic_write(self._key_path(caller, idempotency_key), (json.dumps({"job": job_id}) + "\n").encode(), 0o600)
-        return {"job": {"id": job_id, "status": "working"}}
+        With `idempotency_key` the key is kept per `caller` (the authenticated caller, DEC-0087) beside the digest of the
+        intent (the capability and its input): a key that names a job of another intent raises `idempotency-conflict`;
+        one that names a job of this intent starts nothing and raises InteropError, unless `repeat` would answer "run"
+        (a limit no longer holds, an approval granted); then the key names the new job. A 0.40.0 key file: see `repeat`."""
+        with self._lock:
+            intent = None
+            if idempotency_key is not None:
+                intent = intent_digest(capability, arguments)
+                decision = self.repeat(caller, idempotency_key, now if now is not None else _fs.now_iso(), limit_holds=limit_holds,
+                                       approval_granted=approval_granted, capability=capability, arguments=arguments)
+                if decision["decision"] == "conflict":
+                    raise InteropError("idempotency-conflict: key %s names a job of another intent; send the same capability and input, or a new key." % idempotency_key)
+                if decision["decision"] == "same":
+                    raise InteropError("Key %s already names job %s; answer with that job (JobStore.repeat)." % (idempotency_key, decision["job"]["id"]))
+            job_id = "job_" + secrets.token_hex(12)
+            job: Dict[str, Any] = {"id": job_id, "status": "working"}
+            if poll_interval_ms:
+                job["pollIntervalMs"] = int(poll_interval_ms)
+            private: Dict[str, Any] = {"capability": capability, "input": arguments,
+                                       "traceparent": traceparent if parse_traceparent(traceparent) else None}
+            if delegation:  # DEC-0039: who started it; only they read, cancel or answer it
+                private["delegation"] = {"principal": delegation.get("principal"), "caller": delegation.get("caller")}
+            self._save({"job": job, "private": private})
+            if idempotency_key is not None:
+                _fs.atomic_write(self._key_path(caller, idempotency_key), (json.dumps({"job": job_id, "intent": intent}) + "\n").encode(), 0o600)
+            return {"job": {"id": job_id, "status": "working"}}
 
     def _key_path(self, caller: Optional[str], key: str) -> Path:
-        import hashlib
         if not isinstance(key, str) or not key:
             raise InteropError("An idempotency key is a non-empty string.")
+        if _SURROGATE.search(key) or (isinstance(caller, str) and _SURROGATE.search(caller)):
+            raise InteropError("An idempotency key and its caller are Unicode text; a lone surrogate is refused.")
         name = hashlib.sha256(json.dumps([caller, key], separators=(",", ":"), ensure_ascii=False).encode("utf-8")).hexdigest()  # as JSON.stringify writes it
         directory = self.dir / "keys"
         _fs.ensure_private_dir(directory)
         return directory / ("%s.json" % name)
 
+    def _key_record(self, caller: Optional[str], key: str) -> Optional[Dict[str, Any]]:
+        try:
+            record = json.loads(self._key_path(caller, key).read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return None
+        except ValueError:
+            record = None
+        if not isinstance(record, dict):
+            raise InteropError("Key %s is unreadable on disk." % key)
+        return record
+
     def repeat(self, caller: Optional[str], key: str, now: Any, limit_holds: Optional[bool] = None,
-               approval_granted: bool = False) -> Dict[str, Any]:
-        """The answer to a key this caller sent before (DEC-0087): {"decision": "new"|"same"|"run", "job": job or None}.
-        "same": answer with that job, never run it again (outcome-unknown above all); "run": the intent runs again, once."""
+               approval_granted: bool = False, *, capability: Optional[str] = None, arguments: Any = None) -> Dict[str, Any]:
+        """The answer to a key this caller sent before (DEC-0087): {"decision": "new"|"same"|"run"|"conflict", "job"}. "same": answer with
+        that job, never run it again (outcome-unknown above all); "run": the intent runs again, once; "conflict": given `capability` and
+        its input `arguments`, the key was kept beside another intent (FAA-77). A 0.40.0 key file ({"job": id}) never answers "conflict"."""
+        record = self._key_record(caller, key)
+        if record is None:
+            return {"decision": "new", "job": None}
         try:
-            job_id = json.loads(self._key_path(caller, key).read_text(encoding="utf-8"))["job"]
-            job = self.get(job_id)
-        except (FileNotFoundError, UnknownJob):
+            job = self.get(record["job"])
+        except UnknownJob:
             return {"decision": "new", "job": None}
-        except (ValueError, KeyError, TypeError):
+        except (KeyError, TypeError):
             raise InteropError("Key %s is unreadable on disk." % key) from None
-        return {"decision": repeated_key_decision(job, now, limit_holds, approval_granted), "job": job}
+        decision = repeated_key_decision(job, now, limit_holds, approval_granted)
+        if capability is not None:
+            intent = intent_digest(capability, arguments)
+            if "intent" in record:
+                decision = "conflict" if record["intent"] != intent else decision
+            elif decision == "run":  # a 0.40.0 key runs only the intent its job stored (an input with no JSON form is refused)
+                decision = "run" if intent_digest(*map(self.private(record["job"]).get, ("capability", "input"))) == intent else "same"
+        return {"decision": decision, "job": job}
 
     def get(self, job_id: str) -> Dict[str, Any]:
         return dict(self._load(job_id)["job"])
@@ -620,15 +654,16 @@ class JobStore:
         return self._load(job_id)["private"].get("traceparent")
 
     def _transition(self, job_id: str, status: str, **fields: Any) -> Dict[str, Any]:
-        record = self._load(job_id)
-        job = record["job"]
-        if job["status"] in TERMINAL:
-            raise InteropError("Job %s is already %s; a terminal job does not change." % (job_id, job["status"]))
-        for key in ("inputRequests", "result", "error", "statusMessage"):
-            job.pop(key, None)
-        job["status"] = status
-        job.update({key: value for key, value in fields.items() if value is not None})
-        return self._save(record)
+        with self._lock:
+            record = self._load(job_id)
+            job = record["job"]
+            if job["status"] in TERMINAL:
+                raise InteropError("Job %s is already %s; a terminal job does not change." % (job_id, job["status"]))
+            for key in ("inputRequests", "result", "error", "statusMessage"):
+                job.pop(key, None)
+            job["status"] = status
+            job.update({key: value for key, value in fields.items() if value is not None})
+            return self._save(record)
 
     def working(self, job_id: str, message: Optional[str] = None) -> Dict[str, Any]:
         return self._transition(job_id, "working", statusMessage=message)
@@ -646,15 +681,16 @@ class JobStore:
         """Apply inputResponses to an input_required job; unknown keys are ignored (MCP Tasks rule).
 
         Returns the responses that matched; when any did, the job is working again."""
-        job = self.get(job_id)
-        if job["status"] != "input_required":
-            return {}
-        matched = {key: value for key, value in (input_responses or {}).items()
-                   if key in job.get("inputRequests", {}) and isinstance(value, dict)
-                   and value.get("action") in ("accept", "decline", "cancel")}
-        if matched:
-            self.working(job_id)
-        return matched
+        with self._lock:
+            job = self.get(job_id)
+            if job["status"] != "input_required":
+                return {}
+            matched = {key: value for key, value in (input_responses or {}).items()
+                       if key in job.get("inputRequests", {}) and isinstance(value, dict)
+                       and value.get("action") in ("accept", "decline", "cancel")}
+            if matched:
+                self.working(job_id)
+            return matched
 
     def complete(self, job_id: str, envelope: Dict[str, Any]) -> Dict[str, Any]:
         """The envelope carries the job's trace, authoritative for the stored result (DEC-0017); one that names
@@ -680,13 +716,10 @@ class JobStore:
         """A job a limit paused and its provider will resume (DEC-0087): working, its statusMessage in the pause grammar,
         and pollIntervalMs reaching the reset within its cap of one hour."""
         message = pause_message(resets_at, text)
-        record = self._load(job_id)
-        if resets_at is not None:
-            wait = utc_time(resets_at) - utc_time(_fs.now_iso())
-            if wait > 0:
-                record["job"]["pollIntervalMs"] = int(min(wait, 3600000))
-                self._save(record)
-        return self._transition(job_id, "working", statusMessage=message)
+        wait = utc_time(resets_at) - utc_time(_fs.now_iso()) if resets_at is not None else 0
+        # One write, after the terminal check: a terminal job does not change, pollIntervalMs included (finding 11).
+        return self._transition(job_id, "working", statusMessage=message,
+                                pollIntervalMs=int(min(wait, 3600000)) if wait > 0 else None)
 
     def quota_exhausted(self, job_id: str, message: str, retryable: bool, resets_at: Optional[str] = None) -> Dict[str, Any]:
         """A job a limit stopped and its provider will not resume: failed, quota-exhausted, data {retryable, resetsAt?}."""
@@ -791,7 +824,8 @@ def mcp_header_problem(message: Any, headers: Any) -> Optional[str]:
         return "Mcp-Method %s disagrees with the body's method %s" % (sent, method)
     field = NAMED_METHODS.get(str(method))
     if field:
-        value = (message.get("params") or {}).get(field)
+        params = message.get("params")
+        value = params.get(field) if isinstance(params, dict) else None
         named = header("Mcp-Name")
         if named is None and declared:
             return "the body carries params.%s but the required Mcp-Name header is absent" % field
@@ -878,8 +912,11 @@ class McpToolServer:
         if "id" not in message:
             return None  # a notification gets no response
         rid = message["id"]
-        params = message.get("params") or {}
-        meta = params.get("_meta") or {}
+        params = {} if message.get("params") is None else message["params"]
+        meta = params.get("_meta") if isinstance(params, dict) else None
+        meta = {} if meta is None else meta
+        if not isinstance(params, dict) or not isinstance(meta, dict):  # finding 17: answered, never a crash
+            return self._error(rid, -32602, "params and params._meta are JSON objects.")
         span = child_traceparent(meta.get("traceparent"))
         method = message["method"]
         if method == "initialize":
@@ -898,7 +935,9 @@ class McpToolServer:
         if method != "tools/call":
             return self._error(rid, -32601, "Method %s is not served here." % method)
         name = params.get("name")
-        arguments = params.get("arguments") or {}
+        arguments = {} if params.get("arguments") is None else params["arguments"]
+        if not isinstance(name, str) or not isinstance(arguments, dict):
+            return self._error(rid, -32602, "A tool call names its tool as a string and passes its arguments as a JSON object.")
         if name in ("fabric.job.get", "fabric.job.cancel") and self.jobs is not None:
             verdict = None
             if self._authorize is not None:
@@ -941,7 +980,10 @@ class McpToolServer:
             if name == "fabric.job.cancel":
                 state = self.jobs.get(job_id)
                 if state["status"] not in TERMINAL:
-                    state = self.jobs.cancel(job_id)
+                    try:
+                        state = self.jobs.cancel(job_id)
+                    except InteropError:  # it ended meanwhile: answer as it ended
+                        state = self.jobs.get(job_id)
                 return tool_result({"job": state}, traceparent=job_span)
             responses = arguments.get("inputResponses")
             if responses:

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

@@ -0,0 +1,310 @@
+"""JavaScript's view of JSON values, once for the whole kit (FAA-65, layer L0).
+
+The contract's answers are computed by TypeScript, so a kit that reads JSON the way Python does disagrees with them on
+the edges: `5.0` is a count, an integer beyond a double is Infinity, `String({"toString": 1})` throws, object keys
+that look like array indexes come first. Every reader in the kit takes those semantics from here:
+
+- ``js_string`` (``String()``), ``show`` (the contract's ``show``: ``String()``, or JSON where it would throw),
+  ``json_stringify`` (``JSON.stringify``), ``js_to_number`` (``Number()``), ``double``, ``safe_integer``;
+- ``same`` (``===``) and ``contains``, ``get`` with the ``MISSING`` sentinel for an absent member;
+- ``jcs`` (RFC 8785 canonical JSON) and the number formatting it shares with ``js_string``.
+
+Standard library only; nothing here imports another kit module.
+"""
+from __future__ import annotations
+
+import math
+import re
+from typing import Any, Dict, List, Tuple
+
+
+def js_number_string(value: float) -> str:
+    """ECMAScript Number::toString, which RFC 8785 §3.2.2.3 prescribes."""
+    if value == 0:
+        return "0"
+    if value < 0:
+        return "-" + js_number_string(-value)
+    digits, exponent = _shortest(value)
+    k, n = len(digits), len(digits) + exponent
+    if k <= n <= 21:
+        return digits + "0" * (n - k)
+    if 0 < n <= 21:
+        return digits[:n] + "." + digits[n:]
+    if -6 < n <= 0:
+        return "0." + "0" * (-n) + digits
+    e = n - 1
+    mantissa = digits if k == 1 else digits[0] + "." + digits[1:]
+    return "%se%s%d" % (mantissa, "+" if e >= 0 else "-", abs(e))
+
+
+def _shortest(value: float) -> Tuple[str, int]:
+    """The shortest round-trip digits of a positive finite double (Python's repr is shortest round-trip)."""
+    text = repr(value)
+    mantissa, _, exp = text.partition("e")
+    whole, _, frac = mantissa.partition(".")
+    digits = (whole + frac).lstrip("0")
+    exponent = (int(exp) if exp else 0) - len(frac)
+    if not digits:
+        return "0", 0
+    stripped = digits.rstrip("0")
+    exponent += len(digits) - len(stripped)
+    return stripped, exponent
+
+
+JSON_ESCAPES = {'"': '\\"', "\\": "\\\\", "\b": "\\b", "\f": "\\f", "\n": "\\n", "\r": "\\r", "\t": "\\t"}
+
+
+def json_string_literal(value: str) -> str:
+    out = ['"']
+    for ch in value:
+        code = ord(ch)
+        if 0xD800 <= code <= 0xDFFF:
+            raise TypeError("a lone surrogate has no canonical form")
+        if ch in JSON_ESCAPES:
+            out.append(JSON_ESCAPES[ch])
+        elif code < 0x20:
+            out.append("\\u%04x" % code)
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def jcs(value: Any) -> str:
+    """RFC 8785: members sorted by UTF-16 code units, numbers in ECMAScript form, strings as JSON.stringify
+    escapes them. Refuses what has no canonical form: a non-finite number, a lone surrogate, a non-JSON value.
+    A JSON number is a double: an integer beyond 2**53 is written as JavaScript would write it."""
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, int):
+        if abs(value) < 2 ** 53:
+            return str(value)
+        try:
+            return js_number_string(float(value))
+        except OverflowError:
+            raise TypeError("a number beyond a double has no canonical form") from None
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise TypeError("a non-finite number has no canonical form")
+        return js_number_string(value)
+    if isinstance(value, str):
+        return json_string_literal(value)
+    if isinstance(value, list):
+        return "[" + ",".join(jcs(item) for item in value) + "]"
+    if isinstance(value, dict):
+        if not all(isinstance(key, str) for key in value):
+            raise TypeError("only string member names have a canonical form")
+        keys = sorted(value, key=lambda key: key.encode("utf-16-be", "surrogatepass"))
+        return "{" + ",".join(json_string_literal(key) + ":" + jcs(value[key]) for key in keys) + "}"
+    raise TypeError("%s has no canonical form" % type(value).__name__)
+
+
+MISSING = object()
+
+
+def js_string(value: Any) -> str:
+    """String(value) for a JSON value."""
+    if value is MISSING:
+        return "undefined"
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, float):
+        if math.isnan(value):
+            return "NaN"
+        if math.isinf(value):
+            return "Infinity" if value > 0 else "-Infinity"
+        return js_number_string(value)
+    if isinstance(value, int):
+        if abs(value) < 2 ** 53:
+            return str(value)
+        try:
+            return js_number_string(float(value))
+        except OverflowError:  # a JSON number beyond a double is Infinity in JavaScript
+            return "Infinity" if value > 0 else "-Infinity"
+    if isinstance(value, dict):
+        return "[object Object]"
+    if isinstance(value, list):
+        return ",".join("" if item is None else js_string(item) for item in value)
+    return str(value)
+
+
+def get(value: Any, key: str) -> Any:
+    return value.get(key, MISSING) if isinstance(value, dict) else MISSING
+
+
+def get_string(value: Any, key: str) -> str:
+    return js_string(get(value, key))
+
+
+def is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def double(value: Any) -> float:
+    """A JSON number as JavaScript holds it: the nearest double, and an integer beyond the double range ±Infinity."""
+    try:
+        return float(value)
+    except OverflowError:
+        return math.inf if value > 0 else -math.inf
+
+
+def same(a: Any, b: Any) -> bool:
+    """JavaScript's === (and a Set's SameValueZero) on parsed JSON: an object equals only itself."""
+    if a is MISSING or b is MISSING:
+        return a is b
+    if isinstance(a, (dict, list)) or isinstance(b, (dict, list)):
+        return a is b
+    if isinstance(a, bool) or isinstance(b, bool):
+        return isinstance(a, bool) and isinstance(b, bool) and a == b
+    if is_number(a) and is_number(b):
+        return double(a) == double(b)  # 2**53 + 1 is 2**53 in JavaScript
+    return type(a) is type(b) and a == b
+
+
+def contains(items: List[Any], value: Any) -> bool:
+    return any(same(item, value) for item in items)
+
+
+#: The characters JavaScript's StringToNumber trims: WhiteSpace and LineTerminator (ECMA-262 §12.2, §12.3).
+_JS_SPACE = "\t\n\v\f\r              

  　"
+
+
+_JS_DECIMAL = re.compile(r"[+-]?(?:(?:[0-9]+\.?[0-9]*|\.[0-9]+)(?:[eE][+-]?[0-9]+)?|Infinity)", re.ASCII)
+
+
+_JS_RADIX = re.compile(r"0(?:[xX](?P<x>[0-9a-fA-F]+)|[oO](?P<o>[0-7]+)|[bB](?P<b>[01]+))", re.ASCII)
+
+
+def js_to_number(value: Any) -> float:
+    """Number(value) for a JSON value, as JavaScript reads it; NaN for what it cannot read as a number."""
+    if value is MISSING:
+        return math.nan
+    if value is None:
+        return 0.0
+    if isinstance(value, bool):
+        return 1.0 if value else 0.0
+    if is_number(value):
+        try:
+            return float(value)
+        except OverflowError:
+            return math.inf if value > 0 else -math.inf
+    if isinstance(value, list):
+        return js_to_number(js_string(value))  # Number([2]) is Number("2"); Number([]) is 0
+    if isinstance(value, str):
+        text = value.strip(_JS_SPACE)
+        if text == "":
+            return 0.0
+        if _JS_DECIMAL.fullmatch(text):
+            return float(text.replace("Infinity", "inf"))
+        radix = _JS_RADIX.fullmatch(text)
+        if radix:
+            digits, base = next((radix.group(k), b) for k, b in (("x", 16), ("o", 8), ("b", 2)) if radix.group(k))
+            return double(int(digits, base))
+    return math.nan
+
+
+def safe_integer(value: Any) -> bool:
+    if isinstance(value, int) and not isinstance(value, bool):
+        return abs(value) <= 2 ** 53 - 1  # checked before any float: a 400-digit integer would overflow
+    return isinstance(value, float) and math.isfinite(value) and value.is_integer() and abs(value) <= 2 ** 53 - 1
+
+
+def objects(value: Any) -> List[Dict[str, Any]]:
+    return [item for item in value if isinstance(item, dict)] if isinstance(value, list) else []
+
+
+def indexed_objects(value: Any) -> List[Tuple[Dict[str, Any], int]]:
+    """The object items of an array with their index in the array as written, so an instancePath names the item it
+    flags even when a non-object precedes it (the contract's ``indexed``)."""
+    return [(item, i) for i, item in enumerate(value) if isinstance(item, dict)] if isinstance(value, list) else []
+
+
+class Unshowable(Exception):
+    pass
+
+
+def strict_string(value: Any) -> str:
+    """String(value), raising where JavaScript's String() throws: an object whose own ``toString`` is not a function
+    (every own member of parsed JSON is data), directly or inside an array it joins."""
+    if isinstance(value, dict):
+        if "toString" in value:
+            raise Unshowable()
+        return "[object Object]"
+    if isinstance(value, list):
+        return ",".join("" if item is None else strict_string(item) for item in value)
+    return js_string(value)
+
+
+_INDEX_KEY = re.compile(r"0|[1-9][0-9]*", re.ASCII)
+
+
+def js_keys(value: Dict[str, Any]) -> List[str]:
+    """An object's own keys in the order JavaScript lists them: array-index keys ("0" … "4294967294", no leading zero)
+    ascending, then the others in the order written."""
+    index = sorted((k for k in value if _INDEX_KEY.fullmatch(k) and int(k) <= 2 ** 32 - 2), key=int)
+    taken = set(index)
+    return index + [k for k in value if k not in taken]
+
+
+def json_string(text: str) -> str:
+    """JSON.stringify of a string (well-formed, ES2019): a lone surrogate is escaped as \\uXXXX, never refused."""
+    out = ['"']
+    for ch in text:
+        code = ord(ch)
+        if ch in JSON_ESCAPES:
+            out.append(JSON_ESCAPES[ch])
+        elif code < 0x20 or 0xD800 <= code <= 0xDFFF:
+            out.append("\\u%04x" % code)
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def json_stringify(value: Any) -> str:
+    """JSON.stringify for a parsed JSON value: members in JavaScript's key order, numbers as JavaScript writes them, a
+    lone surrogate escaped."""
+    if isinstance(value, dict):
+        return "{" + ",".join(json_string(k) + ":" + json_stringify(value[k]) for k in js_keys(value)) + "}"
+    if isinstance(value, list):
+        return "[" + ",".join(json_stringify(v) for v in value) + "]"
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if is_number(value):
+        text = js_string(value)
+        return "null" if text in ("NaN", "Infinity", "-Infinity") else text
+    return json_string(value)
+
+
+def show(value: Any) -> str:
+    """The contract's ``show``: String(value), or the value's JSON where String() would throw."""
+    try:
+        return strict_string(value)
+    except Unshowable:
+        return json_stringify(value)
+
+
+def key_of(*parts: Any) -> str:
+    """The contract's ``keyOf``: a collision-free key over JSON values, JSON.stringify of the parts (an absent value
+    is null inside an array, as JavaScript writes it)."""
+    return json_stringify([None if part is MISSING else part for part in parts])
+from typing import Any
+
+
+def json_equal(a: Any, b: Any) -> bool:
+    """The contract's jsonEqual: arrays in order, objects by their members, primitives as JavaScript's ===."""
+    if isinstance(a, list) or isinstance(b, list):
+        return isinstance(a, list) and isinstance(b, list) and len(a) == len(b) and all(json_equal(x, y) for x, y in zip(a, b))
+    if isinstance(a, dict) or isinstance(b, dict):
+        return isinstance(a, dict) and isinstance(b, dict) and len(a) == len(b) and all(k in b and json_equal(a[k], b[k]) for k in a)
+    return same(a, b)