@passioncode-ai/passioncode 0.2.39 → 0.2.41

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-supervisors.mjs

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { credentialName, secretArgument, secretUrl, secretValue } from './fabric-secrets.mjs';
 import { DRAIN_SECONDS, SUPERVISOR_ENV, ServiceError, TASK, UNIT } from './fabric-base.mjs';
-import { atomicWrite, serviceDirs } from './fabric-paths.mjs';
+import { atomicWrite, instanceDirs } from './fabric-paths.mjs';
 import { SUPERVISOR_ARG, markerArguments } from './fabric-lock.mjs';
 import { URI } from './fabric-backups.mjs';
 
@@ -370,14 +370,15 @@ export async function launchdInstall(label, plistPath, plistText, { origin, serv
 /**
  * Symmetric with launchdInstall (LC-14): bootout and WAIT until the job is gone, remove the plist, and reset the
  * override to enabled — launchctl has no verb that deletes an override, and a leftover `disabled` would keep a later
- * fresh install off. Data stays unless `purge` (then `serviceId` names whose data, logs and cache go). A job still
+ * fresh install off. Data stays unless `purge` (then `serviceId` names whose data, logs and cache go, and `instance` which
+ * instance's, so one context's purge never reaches another's, FAA-125). A job still
  * loaded at `timeout` seconds throws, leaving the plist and the data in place.
  */
-export async function launchdUninstall(label, plistPath, { timeout = 30, purge = false, serviceId, run = defaultRun, platform = process.platform, uid, sleep = pause } = {}) {
+export async function launchdUninstall(label, plistPath, { timeout = 30, purge = false, serviceId, instance = 'default', run = defaultRun, platform = process.platform, uid, sleep = pause } = {}) {
   const domain = launchdDomain(platform, uid);
   launchdLabel(label);
   if (purge && !serviceId) throw new ServiceError('purge needs the service id whose data, logs and cache to remove.');
-  const dirs = purge ? serviceDirs(serviceId, platform) : {};
+  const dirs = purge ? instanceDirs(serviceId, instance, platform) : {}; // one instance's folders only (FAA-125)
   const opts = { run, platform, uid };
   const target = `${domain}/${label}`;
   run(['launchctl', 'bootout', target]);

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

@@ -0,0 +1,209 @@
+"""The reading side of an A2A Agent Card (DEC-0122): the well-known document's `surfaces.a2a` member, read as the
+contract's schema reads it (`a2a_surface_findings`, `a2a_view`; `a2a_surface` builds one), and what a public card must
+not carry (`agent_card_findings`): no member about the running process, no secret, no `securitySchemes` entry naming
+the descriptor's token header, every Fabric extension `required: false` (or absent, which A2A reads as false), and interface URLs where the placement puts
+them. Serving a card, the A2A binding and a client are not here (FAA-10). Part of the service kit (layer L3).
+Standard library only."""
+from __future__ import annotations
+
+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_jsvalue import js_keys  # noqa: E402
+from fabric_secrets import secret_value  # noqa: E402
+
+#: A2A 1.0 section 8.2: where a peer looks for the public card.
+A2A_SURFACE_PATH = "/.well-known/agent-card.json"
+#: The A2A version the contract pins (the A2A peer profile); `surfaces.a2a.protocolVersion` is this constant.
+A2A_PROTOCOL_VERSION = "1.0"
+#: The contract's extension namespace (decision D6): an extension whose uri starts here is a Fabric fact.
+FABRIC_EXTENSION_PREFIX = "https://fabric.passioncode.ai/"
+#: The well-known document's members about the running process, which a public card never carries (DEC-0122 item 2).
+PROCESS_MEMBERS = ("build", "process", "pid", "status", "summary", "degraded")
+MAX_PATH = 2048  # service-common.schema.json originPath maxLength, counted in code points as ajv counts it
+
+# JavaScript's \s (the schema's pattern runs under ajv), not Python's: U+FEFF is one, U+001C and U+0085 are not.
+_JS_SPACE = ("\t\n\x0b\x0c\r              "
+             "

  　")
+_ORIGIN_PATH = re.compile("^/(?!/)[^%s]*\\Z" % _JS_SPACE)
+_HTTPS = re.compile(r"^https://", re.IGNORECASE)
+
+
+def _pointer(*parts: Any) -> str:
+    return "".join("/" + str(p).replace("~", "~0").replace("/", "~1") for p in parts)
+
+
+def _ascii_lower(text: str) -> str:
+    return re.sub("[A-Z]", lambda m: m.group(0).lower(), text)
+
+
+def _finding(path: str, keyword: str, message: str) -> Dict[str, str]:
+    return {"instancePath": path, "keyword": keyword, "message": message}
+
+
+def a2a_surface_findings(value: Any, base: str = "/surfaces/a2a") -> List[Dict[str, str]]:
+    """`surfaces.a2a` against service-well-known.schema.json at the pin, in ajv's order: each finding's instancePath
+    and keyword are the schema error's (test/fixtures/contract/a2a-vectors.json), with a sentence."""
+    if not isinstance(value, dict):
+        return [_finding(base, "type", "surfaces.a2a is an object {path, protocolVersion}")]
+    found = [_finding(base, "required", "surfaces.a2a has no %s" % k) for k in ("path", "protocolVersion") if k not in value]
+    found += [_finding(base, "additionalProperties", "surfaces.a2a has no member %s: the card names its interfaces, "
+                       "bindings and security schemes (DEC-0122)" % k)
+              for k in value if k not in ("path", "protocolVersion")]
+    if "path" in value:
+        path = value["path"]
+        if not isinstance(path, str):
+            found.append(_finding(base + "/path", "type", "surfaces.a2a.path is a string"))
+        else:
+            if len(path) > MAX_PATH:
+                found.append(_finding(base + "/path", "maxLength", "surfaces.a2a.path is longer than %d characters" % MAX_PATH))
+            if not _ORIGIN_PATH.match(path):
+                found.append(_finding(base + "/path", "pattern", "surfaces.a2a.path is not a path on the service origin "
+                                      "(one leading /, no whitespace)"))
+    if "protocolVersion" in value and not (isinstance(value["protocolVersion"], str) and value["protocolVersion"] == A2A_PROTOCOL_VERSION):
+        found.append(_finding(base + "/protocolVersion", "const", "surfaces.a2a.protocolVersion is %s, the A2A version the "
+                              "contract pins" % A2A_PROTOCOL_VERSION))
+    return found
+
+
+def a2a_surface_problems(value: Any) -> List[str]:
+    """The findings of a2a_surface_findings as sentences; empty when the member is valid."""
+    return [f["message"] for f in a2a_surface_findings(value)]
+
+
+def a2a_surface(path: str = A2A_SURFACE_PATH) -> Dict[str, str]:
+    """The `surfaces.a2a` member for a service that serves its public card at `path` (DEC-0122 item 1)."""
+    surface = {"path": path, "protocolVersion": A2A_PROTOCOL_VERSION}
+    problems = a2a_surface_problems(surface)
+    if problems:
+        raise ServiceError("surfaces.a2a: %s." % "; ".join(problems))
+    return surface
+
+
+def a2a_view(wk: Any) -> Dict[str, Any]:
+    """What a host reads of a well-known document's A2A member; never raises. `declared` is whether `surfaces.a2a`
+    is present, `valid` whether it is the schema's, `path` the card's path when it is, `findings` the schema's."""
+    surfaces = wk.get("surfaces") if isinstance(wk, dict) else None
+    if not isinstance(surfaces, dict) or "a2a" not in surfaces:
+        return {"declared": False, "valid": False, "path": None, "protocolVersion": None, "findings": []}
+    findings = a2a_surface_findings(surfaces["a2a"])
+    valid = not findings
+    return {"declared": True, "valid": valid, "path": surfaces["a2a"]["path"] if valid else None,
+            "protocolVersion": A2A_PROTOCOL_VERSION if valid else None, "findings": findings}
+
+
+def _card(code: str, path: str, message: str) -> Dict[str, str]:
+    return {"code": code, "instancePath": path, "message": message}
+
+
+def _secrets(card: Dict[str, Any]) -> List[Dict[str, str]]:
+    """Every string the card holds that is shaped like a credential, by its place; walked without recursion, in the
+    order JavaScript lists keys, so both twins name the same places in the same order."""
+    found: List[Dict[str, str]] = []
+    stack: List[Any] = [(card, "")]
+    while stack:
+        node, path = stack.pop()
+        if isinstance(node, str):
+            if secret_value(node):
+                found.append(_card("secret", path, "%s holds a value shaped like a credential: a public card carries no "
+                                   "secret (DEC-0122 item 2)" % (path or "the card")))
+        elif isinstance(node, dict):
+            stack.extend((node[k], path + _pointer(k)) for k in reversed(js_keys(node)))
+        elif isinstance(node, list):
+            stack.extend((node[i], path + _pointer(i)) for i in reversed(range(len(node))))
+    return found
+
+
+def _descriptor_schemes(card: Dict[str, Any], header: str) -> List[Dict[str, str]]:
+    """D5: a securitySchemes entry that is an API key in the descriptor's own header. With Authorization (the
+    default) the card cannot show the token, so nothing is reported."""
+    schemes = card.get("securitySchemes")
+    if not isinstance(schemes, dict) or not header or _ascii_lower(header) == "authorization":
+        return []
+    found = []
+    for name in js_keys(schemes):
+        scheme = schemes[name]
+        if not isinstance(scheme, dict):
+            continue
+        key = scheme.get("apiKeySecurityScheme")  # A2A 1.0: one wrapper member per kind
+        if isinstance(key, dict):
+            location, named = key.get("location"), key.get("name")
+        elif scheme.get("type") == "apiKey":  # the OpenAPI shape of A2A before 1.0
+            location, named = scheme.get("in"), scheme.get("name")
+        else:
+            continue
+        if location == "header" and isinstance(named, str) and _ascii_lower(named) == _ascii_lower(header):
+            found.append(_card("descriptor-token-scheme", _pointer("securitySchemes", name),
+                               "securitySchemes.%s is an API key in %s, the descriptor's token header: an A2A interface "
+                               "never takes the descriptor's token (DEC-0122 item 3)" % (name, header)))
+    return found
+
+
+def _fabric_extensions(card: Dict[str, Any]) -> List[Dict[str, str]]:
+    """D6: an extension under the contract's namespace is not required (A2A 1.0 section 4.4.4): `required` false or
+    absent, which A2A reads as false (a protobuf-written card drops a false default); true or a non-boolean is a finding."""
+    capabilities = card.get("capabilities")
+    extensions = capabilities.get("extensions") if isinstance(capabilities, dict) else None
+    if not isinstance(extensions, list):
+        return []
+    found = []
+    for i, extension in enumerate(extensions):
+        uri = extension.get("uri") if isinstance(extension, dict) else None
+        if not isinstance(uri, str) or _ascii_lower(uri[:len(FABRIC_EXTENSION_PREFIX)]) != FABRIC_EXTENSION_PREFIX:
+            continue
+        if "required" in extension and extension["required"] is not False:
+            found.append(_card("fabric-extension-required", _pointer("capabilities", "extensions", i),
+                               "the Fabric extension at capabilities.extensions[%d] is required, so a peer that does not "
+                               "know it cannot call; it carries required: false (DEC-0122 item 4)" % i))
+    return found
+
+
+def _interfaces(card: Dict[str, Any], origin: Optional[str], remote: bool) -> List[Dict[str, str]]:
+    """Where the card's interfaces are (DEC-0122 item 2): on a local placement on the service's loopback origin as
+    written, on a remote one https; every one A2A 1.0."""
+    interfaces = card.get("supportedInterfaces")
+    if not isinstance(interfaces, list) or not interfaces:
+        return [_card("interfaces-missing", "/supportedInterfaces", "the card names no supportedInterfaces: A2A 1.0 "
+                      "lists a card's interfaces there")]
+    found = []
+    for i, interface in enumerate(interfaces):
+        place = _pointer("supportedInterfaces", i)
+        url = interface.get("url") if isinstance(interface, dict) else None
+        if not isinstance(url, str):
+            found.append(_card("interface-shape", place, "supportedInterfaces[%d] is not an interface with a url" % i))
+            continue
+        if remote:
+            if not _HTTPS.match(url):
+                found.append(_card("interface-scheme", place + "/url", "supportedInterfaces[%d].url is not https: a "
+                                   "loopback or plain-http interface is admitted on a local placement only" % i))
+        elif origin and not (url == origin or url.startswith(origin + "/")):
+            found.append(_card("interface-origin", place + "/url", "supportedInterfaces[%d].url is not on the service "
+                               "origin %s, where a peer on this computer reaches it" % (i, origin)))
+        if not (isinstance(interface.get("protocolVersion"), str) and interface["protocolVersion"] == A2A_PROTOCOL_VERSION):
+            found.append(_card("interface-version", place + "/protocolVersion", "supportedInterfaces[%d] does not expose "
+                               "A2A %s, the version surfaces.a2a names" % (i, A2A_PROTOCOL_VERSION)))
+    return found
+
+
+def agent_card_findings(card: Any, *, origin: Optional[str] = None, remote: bool = False,
+                        descriptor_header: Optional[str] = "Authorization") -> List[Dict[str, str]]:
+    """What a public Agent Card must not carry or say (DEC-0122 items 2 to 4; decisions D5, D6), each finding
+    {code, instancePath, message} naming the place and never the value. `origin` is the service origin the card was
+    read on (its interfaces' place on a local placement; omitted, the place is not judged), `remote` the placement,
+    `descriptor_header` the descriptor's `auth.header` (default Authorization). It reads the card only: whether an
+    interface accepts the token cannot be seen without sending it, which DEC-0122 forbids."""
+    if not isinstance(card, dict):
+        return [_card("card-shape", "", "the card is not a JSON object")]
+    found = [_card("process-member", _pointer(k), "the card carries %s, a member about the running process: a public "
+                   "card carries none (DEC-0122 item 2)" % k) for k in PROCESS_MEMBERS if k in card]
+    found += _secrets(card)
+    found += _descriptor_schemes(card, descriptor_header if isinstance(descriptor_header, str) else "")
+    found += _fabric_extensions(card)
+    found += _interfaces(card, origin, remote)
+    return found

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

@@ -14,6 +14,8 @@ extensions/actions/0.1 (DEC-0121, FAC-SEM-142). Part of the service kit (layer L
   refused when ``decision.schema.json`` would refuse it.
 - ``action_caller(tier, authenticated)``: the caller a service records (AP-2): the identity it authenticated, else
   ``local:T0`` / ``local:T1`` for a caller its local floor authenticated, never a name the call carries.
+- DEC-0125: ``action_decision`` reads a call's mandate (``_meta.mandate``) through fabric_mandate.mandate_covers when the
+  call carries no decision.
 
 The kit has no JSON Schema validator: the two shapes are written here from the schemas, lengths in code points and
 patterns over the whole string, as the contract's validator reads them. Never raises on what it reads. Standard library
@@ -32,7 +34,8 @@ if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from
     _sys.path.insert(0, str(_Path(__file__).resolve().parent))
 
 from fabric_base import ServiceError  # noqa: E402
-from fabric_jsvalue import MISSING, contains, get, json_equal, json_stringify  # noqa: E402
+from fabric_jsvalue import MISSING, contains, get, is_number, json_equal, json_stringify  # noqa: E402
+from fabric_mandate import mandate_covers  # noqa: E402 - DEC-0125
 from fabric_time import format_rfc3339, parse_rfc3339_ms  # noqa: E402
 
 ACTIONS_EXTENSION_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/actions/0.1"
@@ -152,7 +155,13 @@ def action_decision(inputs: Any) -> Dict[str, Any]:
       digest; an accepted elicitation is the operator's; no decision is `operator-decision-required`; a decision that
       is not the schema's, is for another action or object, or whose `at` is more than 60 s ahead of `now` or more
       than 24 h behind it is `decision-invalid`; otherwise the operator's act, recorded with `caller`.
-    - `{"fault": ...}` (action-invalid, caller-missing, now-unreadable, digest-missing, url-missing) is the service's
+    - DEC-0125: a call with no decision that carries `mandate` (its `_meta.mandate`) is answered as
+      fabric_mandate.mandate_covers answers, given `self` (the service's own agent id), `callerAgent` (only an agent id
+      the service authenticated), `effect` (the action's effect class, the service's own knowledge), `spendUsd` (its
+      own estimate) and `project`: covered, `{by: operator, via: mandate, task, chain, caller}`; otherwise
+      `operator-decision-required` or `decision-invalid` with `data.detail`.
+    - `{"fault": ...}` (action-invalid, caller-missing, now-unreadable, digest-missing, url-missing, effect-missing,
+      self-missing) is the service's
       own: an input it owes is missing or unreadable. It is never sent to a caller.
     """
     action = get(inputs, "action")
@@ -182,6 +191,8 @@ def action_decision(inputs: Any) -> Dict[str, Any]:
     if math.isnan(clock):
         return {"fault": "now-unreadable"}
     decision = get(inputs, "decision")
+    if decision is MISSING and get(inputs, "mandate") is not MISSING:
+        return _by_mandate(inputs, action, caller)
     if decision is MISSING:
         return _refuse(OPERATOR_DECISION_REQUIRED)
     if not decision_shape(decision):
@@ -195,6 +206,33 @@ def action_decision(inputs: Any) -> Dict[str, Any]:
     return {"ok": True, "recordAs": {"by": "operator", "via": "relayed-instruction", "caller": caller}}
 
 
+def _by_mandate(inputs: Any, action: Dict[str, Any], caller: str) -> Dict[str, Any]:
+    """A relayed action's call that carries a mandate and no decision (DEC-0125 MD-3): the mandate decides, as the
+    contract's byMandate reads it: the service's own `effect` and agent id `self` are required (else a fault), its
+    estimate `spendUsd` is read when a number and `project` when a string."""
+    effect, me = get(inputs, "effect"), get(inputs, "self")
+    if not isinstance(effect, str):
+        return {"fault": "effect-missing"}
+    if not isinstance(me, str):
+        return {"fault": "self-missing"}
+    call: Dict[str, Any] = {"capability": action["tool"], "action": action["id"], "effect": effect}
+    spend, project = get(inputs, "spendUsd"), get(inputs, "project")
+    if is_number(spend):
+        call["spendUsd"] = spend
+    if isinstance(project, str):
+        call["project"] = project
+    covers: Dict[str, Any] = {"mandate": inputs["mandate"], "tier": get(inputs, "tier"), "now": get(inputs, "now"),
+                              "self": me, "call": call}
+    if get(inputs, "callerAgent") is not MISSING:
+        covers["callerAgent"] = inputs["callerAgent"]
+    answer = mandate_covers(covers)
+    if "recordAs" in answer:
+        record = dict(answer["recordAs"])
+        record["caller"] = caller
+        return {"ok": True, "recordAs": record}
+    return answer  # never `ignored`: the tier was read first, so a T2 call answered approval-required before (MD-5)
+
+
 def actions_view(well_known: Any) -> Dict[str, Any]:
     """The host reader of extensions/actions/0.1 (DEC-0121 AP-1), as the contract's actionsView: `{declared: False}`,
     `{declared: True, valid: False, errors}` or `{declared: True, valid: True, actions}`. Never raises."""

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

@@ -0,0 +1,170 @@
+"""One instance per context (FAA-125, organization row N-11; contract DEC-0082, "One instance per context on a machine"):
+from a context, ``personal`` or ``org:<orgId>``, the service instance, its folders, descriptor and instance lock. Part of
+the service kit (layer L3, after fabric_descriptor); the twin of fabric-context.mjs. Standard library only.
+
+A service started for a context runs as that context's one instance on this machine: its own instance name, descriptor,
+data, log and cache folders and instance lock; a second copy for the same context exits 75 as ``hold_single_instance``
+does; an organization's instance runs only under a placement of this machine's estate record that names an unrevoked
+share grant for that context (FAC-SEM-111), inside the grant's window; a data folder never changes context (its
+``fabric-context.json`` marker). A refusal exits 78 (EX_CONFIG) with nothing created. The facade ``fabric_service`` does
+not re-export this module, so a service that does not run per context keeps the estate reader out of its closure:
+``fabric_kit.py install <dir> --module fabric_context``. Docs: references/estate-record.md (Contexts)."""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import sys
+import time
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional, Sequence, Tuple
+
+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, _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_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
+
+#: EX_CONFIG: the context is refused; 75 stays "already running" (``fabric_lock.EXIT_ALREADY_RUNNING``).
+EXIT_CONTEXT_REFUSED = 78
+CONTEXT_MARKER = "fabric-context.json"
+#: An organization id kept readable in the instance name: lower-case words joined by single hyphens (brief D15).
+_READABLE = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*\Z")
+#: Only a hashed name ends in a hyphen and 10 hex digits, so a readable and a hashed name never meet.
+_HASHED_TAIL = re.compile(r"-[0-9a-f]{10}\Z")
+_READABLE_MAX = 28
+_SLUG_MAX = 17
+#: What each refusal tells the person; the sentence never carries a record or grant value.
+_REASONS = {
+    "context-invalid": "the context is neither personal nor org:<orgId> as written",
+    "record-required": "an organization's instance needs this machine's estate record, its machine id and its agentRef",
+    "placement-missing": "the estate record places no such agent on this machine in that context",
+    "grant-refused": "its placement names no unrevoked share grant for that context (FAC-SEM-111)",
+    "grant-window": "now is outside its share grant's window",
+    "context-mismatch": "its data folder belongs to another context or instance (%s)" % CONTEXT_MARKER,
+}
+
+
+class ContextRefused(ServiceError):
+    """A context this machine does not run. ``code``: context-invalid, record-required, placement-missing,
+    grant-refused, grant-window or context-mismatch."""
+
+    def __init__(self, code: str, detail: str = ""):
+        self.code = code
+        self.detail = detail
+        super().__init__("%s: %s." % (code, detail or _REASONS[code]))
+
+
+def _shown(context: Any) -> str:
+    return context if parse_context(context) else "a context that is neither personal nor org:<orgId>"
+
+
+def context_instance_name(context: Any, *, personal_instance: str = "default") -> str:
+    """The instance name of ``context`` (brief D15): ``personal`` is ``personal_instance`` (``default``, so an existing
+    install keeps its descriptor, folders and lock); ``org:<orgId>`` is ``org-<orgId>`` when the id is lower-case words
+    joined by single hyphens, at most 28 characters, and does not end in a hyphen and 10 hex digits; otherwise
+    ``org-<slug>-<first 10 hex digits of sha256(orgId)>``. Every name is a descriptor's instance. Raises ContextRefused."""
+    parsed = parse_context(context)
+    if parsed is None:
+        raise ContextRefused("context-invalid")
+    if parsed["kind"] == "personal":
+        if not isinstance(personal_instance, str) or not _INSTANCE.match(personal_instance) or personal_instance.startswith("org-"):
+            raise ContextRefused("context-invalid", "the personal instance %r is no instance name outside org-" % (personal_instance,))
+        return personal_instance
+    org = parsed["org"]
+    if _READABLE.match(org) and len(org) <= _READABLE_MAX and not _HASHED_TAIL.search(org):
+        return "org-" + org
+    slug = re.sub(r"[^a-z0-9]+", "-", org.lower()).strip("-")[:_SLUG_MAX].strip("-") or "x"
+    return "org-%s-%s" % (slug, hashlib.sha256(org.encode("utf-8")).hexdigest()[:10])
+
+
+def context_instance(service_id: str, context: Any, *, record: Optional[Dict[str, Any]] = None,
+                     machine_id: Optional[str] = None, agent_ref: Optional[str] = None, at: Any = None,
+                     personal_instance: str = "default", services_directory: Optional[Path] = None) -> Dict[str, Any]:
+    """What ``context`` runs as on this machine; pure (no folder, file or lock). Answers ``{"context", "kind":
+    "personal"|"org", "org"?, "instance", "key": "<id>.<instance>", "dirs": {"data", "logs", "cache"},
+    "descriptorPath", "grant"?: {"id", "startsAt"?, "expiresAt"?}}``, never the record. Raises ContextRefused.
+
+    ``record`` is the estate record revision this machine applied, already verified (``verify_estate_record``); the
+    helper reads it and verifies no signature. ``machine_id`` and ``agent_ref`` come from whoever installed the
+    instance, never guessed. ``at`` is the clock (an aware datetime or epoch seconds; now when None)."""
+    instance = context_instance_name(context, personal_instance=personal_instance)
+    parsed = parse_context(context)
+    dirs = instance_dirs(service_id, instance)
+    answer: Dict[str, Any] = {"context": context, "kind": parsed["kind"], "instance": instance,
+                              "key": "%s.%s" % (service_id, instance), "dirs": dirs,
+                              "descriptorPath": descriptor_path(service_id, instance, services_directory)}
+    have_place = isinstance(record, dict) and isinstance(machine_id, str) and isinstance(agent_ref, str)
+    at_ms = time.time() * 1000.0 if at is None else clock_ms(at)
+    if parsed["kind"] == "personal":
+        if have_place:  # brief D20: a personal placement that names a grant is refused; no placement is no refusal
+            checked = instance_share_grant(record, machine_id, agent_ref, context, at_ms)
+            if not checked["ok"] and checked["code"] == "grant-refused":
+                raise ContextRefused("grant-refused", checked["detail"])
+        return answer
+    answer["org"] = parsed["org"]
+    if not have_place:
+        raise ContextRefused("record-required")
+    checked = instance_share_grant(record, machine_id, agent_ref, context, at_ms)
+    if not checked["ok"]:
+        raise ContextRefused(checked["code"], checked["detail"])
+    answer["grant"] = checked["grant"]
+    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 _marker_matches(path: Path, expected: Dict[str, str]) -> Optional[bool]:
+    """True when the marker names this instance, False when it names another or cannot be read, None when absent."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+    except OSError:
+        return False
+    try:
+        found = json.loads(text)
+    except ValueError:
+        return False
+    return isinstance(found, dict) and all(found.get(key) == value for key, value in expected.items())
+
+
+def hold_context_instance(service_id: str, context: Any, *, record: Optional[Dict[str, Any]] = None,
+                          machine_id: Optional[str] = None, agent_ref: Optional[str] = None, at: Any = None,
+                          personal_instance: str = "default", wait_seconds: Optional[float] = None,
+                          sleep: Callable[[float], None] = time.sleep, clock: Callable[[], float] = time.monotonic,
+                          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
+    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."""
+    try:
+        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)
+    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
+    try:
+        matches = _marker_matches(marker, expected)
+        if matches is None:
+            atomic_write(marker, (json.dumps(expected, indent=1) + "\n").encode("utf-8"), mode=0o600)
+    except BaseException:
+        lock.release()
+        raise
+    if matches is False:
+        lock.release()
+        _refuse(service_id, context, "context-mismatch")
+    return info, lock

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

@@ -45,6 +45,7 @@ from fabric_jsvalue import (  # noqa: E402 - the core (FAA-65)
     jcs,
 )
 from fabric_paths import atomic_write as _atomic_write  # noqa: E402 - the kit's private writer (FAA-85)
+from fabric_mandate import effect_closure  # noqa: E402,F401 - defined once beside the mandate that reads it too (DEC-0125)
 
 REFUSAL_CODES = (
     "unauthenticated", "token-expired", "wrong-audience", "scope-not-granted", "effect-above-ceiling", "no-grant",
@@ -93,7 +94,11 @@ REFUSAL_MESSAGES = {
     "issuer-unavailable": "The estate's published keys cannot be read.",
     "unknown-state": "The state cannot be established, so the call is refused.",
     # DEC-0121 (AP-2, AP-4): the refusals of an action call; each answers 403.
-    "operator-decision-required": "This action is the operator's decision; ask the operator and call again with it in _meta.decision.",
+    "operator-decision-required": ("This action is the operator's decision; ask the operator and call again with it in "
+                                   "_meta.decision. A client that cannot set _meta: Fabric's agent.call with "
+                                   "call.decision, once the hub forwards it; else this service's own elicitation, "
+                                   "where the client shows one; else the action's page handed to the operator as "
+                                   "Fabric Dashboards' open_link."),
     "decision-invalid": "The call's decision is not valid for this action, object or time.",
     "human-step-required": "This step is the person's own; hand them the link in error.data.url.",
 }
@@ -299,16 +304,6 @@ def _chain_of(act: Dict[str, Any]) -> List[str]:
     return chain
 
 
-def effect_closure(ceiling: List[str]) -> set:
-    """`none` is below every class and `draft` below every external one; external classes are not ordered."""
-    admitted = set(ceiling)
-    if ceiling:
-        admitted.add("none")
-    if any(effect != "none" for effect in ceiling):
-        admitted.add("draft")
-    return admitted
-
-
 def effect_within(effect: str, ceiling: List[str]) -> bool:
     return effect in effect_closure(ceiling)
 
@@ -822,11 +817,19 @@ def refusal_from_action(answer: Any) -> Optional[Dict[str, Any]]:
     return _refuse(code, _ACTION_DETAILS[code], dict(data) if isinstance(data, dict) and data else None)
 
 
+#: DEC-0125 MD-4: a refusal outside a mandate goes back up the chain; only the leading agent asks the operator.
+OUTSIDE_MANDATE_MESSAGE = ("Outside the operator's mandate for this call. Call again within your own mandate if it covers this part; else pass this refusal to the agent that called you. Only the leading agent asks the operator, once, about this part alone, then relays a decision or mandate that covers it: in _meta, or, without _meta, through Fabric's agent.call once the hub forwards it, the service's elicitation, or the action's page as a Fabric Dashboards open_link (DEC-0125 MD-4).")
+
+
 def refusal_error(refusal: Dict[str, Any]) -> Dict[str, Any]:
     """The DL-19 body: {error: {code, message, data: {detail, ...}}}; never a token or a key."""
     data = {"detail": refusal["detail"]}
     data.update(refusal.get("data") or {})
-    return {"error": {"code": refusal["code"], "message": REFUSAL_MESSAGES.get(refusal["code"], "Refused."), "data": data}}
+    # the gate's answer keeps no-decision at the top and its outside-mandate part in data.detail; only a string names a part
+    part = data.get("detail") if isinstance(data.get("detail"), str) else refusal["detail"]
+    outside = refusal["code"] == "operator-decision-required" and isinstance(part, str) and part.startswith("outside-mandate:")
+    message = OUTSIDE_MANDATE_MESSAGE if outside else REFUSAL_MESSAGES.get(refusal["code"], "Refused.")
+    return {"error": {"code": refusal["code"], "message": message, "data": data}}
 
 
 def refusal_tool_result(refusal: Dict[str, Any], traceparent: Optional[str] = None) -> Dict[str, Any]:

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

@@ -37,6 +37,7 @@ from fabric_protocols import (
 )
 from fabric_connections import CONNECTIONS_EXTENSION_KEY, connections_view  # noqa: E402 - the kit (FAA-62)
 from fabric_actions import ACTIONS_EXTENSION_KEY, actions_extension, actions_extension_rules  # noqa: E402 - DEC-0121
+from fabric_a2a import a2a_surface_problems  # noqa: E402 - DEC-0122
 from fabric_usage import (
     ROUTES,
 )
@@ -579,7 +580,8 @@ def build_well_known(*, service_id: str, instance: str, name: str, version: str,
                      extensions: Optional[Dict[str, Any]] = None,
                      configuration: Optional[Dict[str, Any]] = None,
                      protocols: Optional[Sequence[str]] = None,
-                     actions: Optional[Sequence[Dict[str, Any]]] = None) -> Dict[str, Any]:
+                     actions: Optional[Sequence[Dict[str, Any]]] = None,
+                     a2a: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     """The unauthenticated identity answer. `degraded` is always present; ready means empty.
     `configuration` (DEC-0046) says what the operator can configure and what applies now; fabric_profiles builds it.
     `extensions` is kept as given (a reader ignores keys it does not know); a dashboard declaration
@@ -587,7 +589,10 @@ def build_well_known(*, service_id: str, instance: str, name: str, version: str,
     `actions` (DEC-0121 AP-1) is the service's action table, every button its dashboard, app or page offers with the
     tool that performs it and its gate; it is written under extensions/actions/0.1 by fabric_actions.actions_extension.
     A declaration FAC-SEM-142 finds, passed either way, is refused: one that is not its schema's, an id named twice, a
-    humanStep that disagrees with the gate, or a tool `surfaces.mcp.capabilities` does not list."""
+    humanStep that disagrees with the gate, or a tool `surfaces.mcp.capabilities` does not list.
+    `a2a` (DEC-0122) is `surfaces.a2a`, where the service serves its public Agent Card (fabric_a2a.a2a_surface builds
+    one); passed here or in `surfaces`, never both, and refused when it is not the schema's. A reader pinned before
+    DEC-0122 refuses the member, so a service carries it only once its readers are pinned at or after it."""
     if status not in STATUSES:
         raise ServiceError("status must be one of %s." % ", ".join(STATUSES))
     degraded = list(degraded)
@@ -595,6 +600,15 @@ def build_well_known(*, service_id: str, instance: str, name: str, version: str,
         status = "degraded"
     if "events" not in surfaces:
         raise ServiceError("surfaces.events is required.")
+    if a2a is not None:
+        if "a2a" in surfaces:
+            raise ServiceError("surfaces.a2a: pass it in surfaces or as a2a, not both.")
+        surfaces = dict(surfaces, a2a=a2a)
+    if "a2a" in surfaces:
+        # DEC-0122: a host reads the member by the schema; a service never publishes one it would refuse.
+        problems = a2a_surface_problems(surfaces["a2a"])
+        if problems:
+            raise ServiceError("surfaces.a2a: %s." % "; ".join(problems))
     doc: Dict[str, Any] = {
         "protocol": PROTOCOL,
         "service": {"id": service_id, "instance": instance, "name": name, "version": version, "build": build},

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

@@ -776,6 +776,13 @@ def _placement_grant_problems(record: Dict[str, Any], placement: Dict[str, Any])
     return problems
 
 
+def placement_grant_findings(record: Any, placement: Any) -> List[Dict[str, str]]:
+    """FAC-SEM-111 for one placement of ``record``, as findings (``instancePath`` relative to the placement). Answers,
+    never raises: a record or placement that is no object reads as an empty one (FAA-125)."""
+    record, placement = (v if isinstance(v, dict) else {} for v in (record, placement))
+    return [{"code": "FAC-SEM-111", "instancePath": at, "message": m} for at, m in _placement_grant_problems(record, placement)]
+
+
 def _placement_grants(value: Dict[str, Any], flag) -> None:
     for machine, m in _indexed(_get(value, "machines")):
         for placement, p in _indexed(_get(machine, "packages")):