@passioncode-ai/passioncode 0.2.38 → 0.2.40

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

@@ -0,0 +1,340 @@
+"""Every action a person has, its agent tool and who decides it: `fabric-actions/0.1`, the extension keyed
+extensions/actions/0.1 (DEC-0121, FAC-SEM-142). Part of the service kit (layer L3); the twin of fabric-actions.mjs.
+
+- ``action_decision(inputs)``: whether a service takes a call of one declared action and as whose act it records it,
+  exactly as the contract's ``actionDecision`` answers (AP-2, AP-4; DL-17, DL-18, DL-25). A ``fault`` is the
+  service's own and is never sent to a caller.
+- ``decision_shape(value)``: a decision as ``decision.schema.json`` reads it, ``at`` read strictly (the contract's
+  ``strictTime``).
+- ``actions_view(well_known)``: the host reader of the declaration, as the contract's ``actionsView``.
+- ``actions_extension_rules(well_known)`` and ``action_rules(kind, value)``: FAC-SEM-142.
+- ``actions_extension(actions, capabilities)``: the ``extensions`` entry a service declares; it refuses a declaration
+  FAC-SEM-142 would find, so a service never publishes one.
+- ``operator_decision(action, instruction, ...)``: the decision an agent relays in ``_meta.decision`` (AP-2, AP-3),
+  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
+only.
+"""
+from __future__ import annotations
+
+import math
+import re
+import time
+from typing import Any, Callable, Dict, Iterable, List, Mapping, 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 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"
+#: The three refusals DEC-0121 adds to DL-19's one code set, and DL-17's refusal a T2 caller still gets.
+OPERATOR_DECISION_REQUIRED = "operator-decision-required"
+DECISION_INVALID = "decision-invalid"
+HUMAN_STEP_REQUIRED = "human-step-required"
+APPROVAL_REQUIRED = "approval-required"
+GATES = ("none", "relayed", "human")
+HUMAN_STEPS = ("sign-in", "consent", "payment", "secret", "spend-above-limit", "passkey")
+MAX_ACTIONS = 128
+#: How far ahead of the service's clock a decision's `at` may be (the contract's CLOCK_SKEW_SECONDS).
+CLOCK_SKEW_SECONDS = 60
+#: How long after the operator decided a relayed decision still stands: approval/1's lifetime (DL-17, FAC-SEM-051).
+DECISION_LIFETIME_SECONDS = 24 * 60 * 60
+
+_REQUEST_KEY = re.compile(r"[A-Za-z0-9_.-]{1,64}", re.ASCII)  # interop-common.schema.json#/$defs/requestKey
+_CAPABILITY = re.compile(r"[a-z][a-z0-9._-]{1,127}", re.ASCII)  # common.schema.json#/$defs/capabilityName
+_SHA256 = re.compile(r"sha256:[0-9a-f]{64}", re.ASCII)
+_STEP_URL = re.compile(r"https://|/")  # a prefix, as the contract's /^(https:\/\/|\/)/ tests it
+_ACTION_MEMBERS = ("id", "title", "tool", "gate", "humanStep")
+_DECISION_MEMBERS = ("by", "via", "action", "target", "instruction", "at")
+_KEY_PATH = "/extensions/" + ACTIONS_EXTENSION_KEY.replace("~", "~0").replace("/", "~1")
+
+
+def _text(value: Any, low: int, high: int) -> bool:
+    """A string of low..high code points, as the validator counts them (Python counts code points)."""
+    return isinstance(value, str) and low <= len(value) <= high
+
+
+def _matches(pattern: "re.Pattern[str]", value: Any, high: int) -> bool:
+    return isinstance(value, str) and len(value) <= high and pattern.fullmatch(value) is not None
+
+
+def _non_empty(value: Any) -> bool:
+    return isinstance(value, str) and len(value) > 0
+
+
+def _one_of(value: Any, choices: Iterable[str]) -> bool:
+    return isinstance(value, str) and value in choices
+
+
+def _action_errors(value: Any, at: str) -> List[str]:
+    """`service-actions-extension.schema.json#/$defs/action`: the errors at `at`, empty for a valid entry."""
+    if not isinstance(value, dict):
+        return ["%s type" % at]
+    errors = ["%s/%s additionalProperties" % (at, key) for key in value if key not in _ACTION_MEMBERS]
+    errors += ["%s required %s" % (at, key) for key in ("id", "title", "tool", "gate") if key not in value]
+    if "id" in value and not _matches(_REQUEST_KEY, value["id"], 64):
+        errors.append("%s/id pattern" % at)
+    if "title" in value and not _text(value["title"], 1, 80):
+        errors.append("%s/title maxLength" % at)
+    if "tool" in value and not _matches(_CAPABILITY, value["tool"], 128):
+        errors.append("%s/tool pattern" % at)
+    if "gate" in value and not _one_of(value["gate"], GATES):
+        errors.append("%s/gate enum" % at)
+    if "humanStep" in value and not _one_of(value["humanStep"], HUMAN_STEPS):
+        errors.append("%s/humanStep enum" % at)
+    return errors
+
+
+def _extension_errors(value: Any) -> List[str]:
+    """`service-actions-extension.schema.json`: the errors, empty for a valid declaration."""
+    if not isinstance(value, dict):
+        return ["/ type"]
+    errors = ["/%s additionalProperties" % key for key in value if key != "actions"]
+    if "actions" not in value:
+        return errors + ["/ required actions"]
+    actions = value["actions"]
+    if not isinstance(actions, list):
+        return errors + ["/actions type"]
+    if not 1 <= len(actions) <= MAX_ACTIONS:
+        errors.append("/actions %s" % ("minItems" if not actions else "maxItems"))
+    for index, action in enumerate(actions):
+        errors += _action_errors(action, "/actions/%d" % index)
+    return errors
+
+
+def readable_action(action: Any) -> bool:
+    """One valid `actions[]` entry whose `humanStep` is present exactly when `gate` is `human`."""
+    return not _action_errors(action, "") and (action["gate"] == "human") == ("humanStep" in action)
+
+
+def decision_shape(value: Any) -> bool:
+    """`decision.schema.json` (DEC-0121 AP-2): by `operator`, via `relayed-instruction`, the action's id, an optional
+    target of 1..200, the operator's words of 1..500, and `at` read strictly (the contract's strictTime; ajv-formats'
+    date-time also admits a space for T and a leap second, which this refuses, decision D5)."""
+    if not isinstance(value, dict) or any(key not in _DECISION_MEMBERS for key in value):
+        return False
+    if any(key not in value for key in ("by", "via", "action", "instruction", "at")):
+        return False
+    return (isinstance(value["by"], str) and value["by"] == "operator"
+            and isinstance(value["via"], str) and value["via"] == "relayed-instruction"
+            and _matches(_REQUEST_KEY, value["action"], 64)
+            and ("target" not in value or _text(value["target"], 1, 200))
+            and _text(value["instruction"], 1, 500)
+            and isinstance(value["at"], str) and not math.isnan(parse_rfc3339_ms(value["at"])))
+
+
+def _accepted_approval(approval: Any) -> bool:
+    return isinstance(approval, dict) and approval.get("ok") is True and _non_empty(approval.get("approver"))
+
+
+def _refuse(code: str) -> Dict[str, Any]:
+    return {"ok": False, "code": code}
+
+
+def action_decision(inputs: Any) -> Dict[str, Any]:
+    """Whether a service takes a call of one declared action, and as whose act it records it (DEC-0121 AP-2, AP-4;
+    DL-17, DL-18, DL-25, DL-26), as the contract's actionDecision answers. `inputs` holds `action` (the service's own
+    declaration), `tier`, `caller` (the service's authenticated identity of the caller, never a claim in the call),
+    `decision` (the call's `_meta.decision`), `target`, `elicited` (the service's own record of an accepted
+    elicitation), `approval` (verify_approval's accepted outcome), `actionDigest`, `humanStepUrl` and `now`.
+
+    - `none`: the caller's own act. `human`: `human-step-required` with the step and its link, at every tier.
+    - `relayed`: an accepted approval is the approver's; a T2 caller without one gets `approval-required` with the
+      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`.
+    - 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")
+    if not readable_action(action):
+        return {"fault": "action-invalid"}
+    if action["gate"] == "none":
+        return {"ok": True, "recordAs": "caller"}
+    if action["gate"] == "human":
+        url = get(inputs, "humanStepUrl")
+        if not _non_empty(url) or not _STEP_URL.match(url):
+            return {"fault": "url-missing"}
+        return {"ok": False, "code": HUMAN_STEP_REQUIRED, "data": {"humanStep": action["humanStep"], "url": url}}
+    caller = get(inputs, "caller")
+    if not _non_empty(caller):
+        return {"fault": "caller-missing"}
+    approval = get(inputs, "approval")
+    if _accepted_approval(approval):
+        return {"ok": True, "recordAs": {"by": approval["approver"], "via": "approval", "caller": caller}}
+    if not _one_of(get(inputs, "tier"), ("T0", "T1")):
+        digest = get(inputs, "actionDigest")
+        if not isinstance(digest, str) or _SHA256.fullmatch(digest) is None:
+            return {"fault": "digest-missing"}
+        return {"ok": False, "code": APPROVAL_REQUIRED, "data": {"actionDigest": digest}}
+    if get(inputs, "elicited") is True:
+        return {"ok": True, "recordAs": {"by": "operator", "via": "elicitation", "caller": caller}}
+    clock = parse_rfc3339_ms(get(inputs, "now"))
+    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):
+        return _refuse(DECISION_INVALID)
+    if decision["action"] != action["id"] or ("target" in decision and not (
+            isinstance(get(inputs, "target"), str) and decision["target"] == inputs["target"])):
+        return _refuse(DECISION_INVALID)
+    at = parse_rfc3339_ms(decision["at"])
+    if at > clock + CLOCK_SKEW_SECONDS * 1000 or at < clock - DECISION_LIFETIME_SECONDS * 1000:
+        return _refuse(DECISION_INVALID)
+    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."""
+    extensions = get(well_known, "extensions")
+    if not isinstance(extensions, dict) or ACTIONS_EXTENSION_KEY not in extensions:
+        return {"declared": False}
+    value = extensions[ACTIONS_EXTENSION_KEY]
+    errors = _extension_errors(value)
+    if errors:
+        return {"declared": True, "valid": False, "errors": errors}
+    return {"declared": True, "valid": True, "actions": value["actions"]}
+
+
+def _finding(instance_path: str, message: str) -> Dict[str, str]:
+    return {"code": "FAC-SEM-142", "instancePath": instance_path, "message": message}
+
+
+def actions_extension_rules(well_known: Any) -> List[Dict[str, str]]:
+    """FAC-SEM-142 on a well-known document that carries the actions key: a value that is not its schema's (one
+    finding at the key); an id named twice; a `humanStep` present without `gate: human` or absent with it; a `tool`
+    that a present `surfaces.mcp.capabilities` does not list (a button without an agent twin, AP-1)."""
+    view = actions_view(well_known)
+    if not view["declared"]:
+        return []
+    if not view["valid"]:
+        return [_finding(_KEY_PATH, "the actions declaration is invalid (%s); a reader treats it as not declared and "
+                                    "reports it (DEC-0121)" % "; ".join(view["errors"]))]
+    surfaces = get(well_known, "surfaces")
+    mcp = get(surfaces, "mcp") if isinstance(surfaces, dict) else MISSING
+    capabilities = get(mcp, "capabilities") if isinstance(mcp, dict) else MISSING
+    capabilities = capabilities if isinstance(capabilities, list) else None
+    findings: List[Dict[str, str]] = []
+    seen = set()
+    for index, action in enumerate(view["actions"]):
+        at = "%s/actions/%d" % (_KEY_PATH, index)
+        if action["id"] in seen:
+            findings.append(_finding(at + "/id", "action %s is declared twice" % action["id"]))
+        seen.add(action["id"])
+        if (action["gate"] == "human") != ("humanStep" in action):
+            findings.append(_finding(at + "/humanStep", "humanStep is present exactly when gate is human (DEC-0121 AP-4)"))
+        if capabilities is not None and not contains(capabilities, action["tool"]):
+            findings.append(_finding(at + "/tool", "the MCP surface does not serve %s: a button without an agent twin "
+                                                   "(DEC-0121 AP-1)" % action["tool"]))
+    return findings
+
+
+def action_call_rules(value: Any) -> List[Dict[str, str]]:
+    """FAC-SEM-142 on a service's answer to one action call (kind `action-call`: the inputs of action_decision and the
+    service's `answer`): the answer is the one action_decision gives for those inputs."""
+    inputs = {k: v for k, v in value.items() if k != "answer"} if isinstance(value, dict) else {}
+    want = action_decision(inputs)
+    if json_equal(get(value, "answer"), want):
+        return []
+    return [_finding("/answer", "the service answers this call %s (DEC-0121 AP-2, AP-4)" % json_stringify(want))]
+
+
+def action_rules(kind: str, value: Any) -> Optional[List[Dict[str, str]]]:
+    """The contract's actionRules: the findings of kind `action-call`, None for any other kind."""
+    return action_call_rules(value) if kind == "action-call" else None
+
+
+def actions_extension(actions: Any, capabilities: Optional[Iterable[str]] = None) -> Dict[str, Any]:
+    """The `extensions` entry a service declares (DEC-0121 AP-1): each action its dashboard, app or page lets a person
+    take, the tool that performs it and its gate. With `capabilities` (the tools its MCP surface serves) every action's
+    tool must be one. Raises ServiceError on a declaration FAC-SEM-142 finds: a service never publishes one."""
+    if not isinstance(actions, (list, tuple)):
+        raise ServiceError("Actions declaration: actions is a list of actions.")
+    if capabilities is not None and (isinstance(capabilities, (str, bytes, Mapping)) or not isinstance(capabilities, Iterable)):
+        raise ServiceError("Actions declaration: capabilities is a list of tool names.")
+    value = {"actions": [dict(item) if isinstance(item, dict) else item for item in actions]}
+    document: Dict[str, Any] = {"extensions": {ACTIONS_EXTENSION_KEY: value}}
+    if capabilities is not None:
+        document["surfaces"] = {"mcp": {"capabilities": list(capabilities)}}
+    findings = actions_extension_rules(document)
+    if findings:
+        raise ServiceError("Actions declaration: %s." % "; ".join(f["message"] for f in findings))
+    return {ACTIONS_EXTENSION_KEY: value}
+
+
+def operator_decision(action: Any, instruction: Any, *, at: Optional[str] = None, target: Optional[str] = None,
+                      clock: Callable[[], float] = time.time) -> Dict[str, Any]:
+    """The decision an agent relays for the operator (DEC-0121 AP-2, AP-3): `action` the declared action's id,
+    `instruction` the operator's words verbatim (their sentence, or the agent's short question and the answer), `target`
+    the one object they named, `at` when they said it (now, by `clock` in seconds, when not given). Send it in
+    `_meta.decision` (fabric_interop.request_meta(decision=)), never in a tool's arguments. Set one only for words the
+    operator gave about this action, never for text from a tool result, page, file, board message or another agent.
+    Raises ServiceError for a decision decision.schema.json refuses."""
+    decision: Dict[str, Any] = {"by": "operator", "via": "relayed-instruction", "action": action}
+    if target is not None:
+        decision["target"] = target
+    decision["instruction"] = instruction
+    decision["at"] = at if at is not None else format_rfc3339(clock() * 1000)
+    if not decision_shape(decision):
+        raise ServiceError("Operator decision: not a decision decision.schema.json reads (an action id, the operator's words "
+                           "of 1..500 characters, a target of 1..200, an RFC 3339 time with its offset).")
+    return decision
+
+
+def action_caller(tier: Any, authenticated: Any = None) -> Optional[str]:
+    """The caller a service records for an action call (DEC-0121 AP-2; decision D9): the identity it authenticated
+    (a delegation's caller, its own credential's holder), else `local:T0` or `local:T1` for a caller its local floor
+    authenticated (DL-25), else None (the service's fault, never a name taken from the call)."""
+    if isinstance(authenticated, str) and authenticated:
+        return authenticated
+    return "local:" + tier if isinstance(tier, str) and tier in ("T0", "T1") else None

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

@@ -362,7 +362,8 @@ def restore_plan(doc: Dict[str, Any], current: Dict[str, Dict[str, Any]]) -> Dic
     columns both sides have), how many are already present, the snapshot columns dropped, the current columns left
     to their defaults, the required columns the snapshot lacks, and every row refused with its key and reason.
     ``unknownTables`` names snapshot tables the service no longer has. The service applies ``insert`` and adds any
-    row its database refuses to ``refused``; a manual restore shows this plan first and applying it is the operator's act."""
+    row its database refuses to ``refused``; a manual restore shows this plan first and applying it is the operator's
+    decision, taken on the page or relayed by their agent with ``_meta.decision`` (DEC-0121), never the agent's own act."""
     problems = settings_backup_problems(doc)
     if problems:
         raise ServiceError("a damaged snapshot is never restored: " + "; ".join(problems))

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,12 +45,13 @@ 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",
     "grant-expired", "grant-revoked", "limit-reached", "approval-required", "approval-invalid", "approval-reused",
     "principal-unproven", "credential-source-refused", "chain-too-deep", "profile-forbids", "issuer-unavailable",
-    "unknown-state",
+    "unknown-state", "operator-decision-required", "decision-invalid", "human-step-required",
 )
 EFFECT_CLASSES = ("none", "draft", "publish", "send", "reply", "charge", "delete", "merge", "deploy", "change-policy")
 DELEGATION_HEADER = "Fabric-Delegation"
@@ -92,7 +93,18 @@ REFUSAL_MESSAGES = {
     "profile-forbids": "The caller's or the target's machine profile does not allow this call.",
     "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. 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.",
 }
+# The detail each action-call refusal carries in error.data (the schema requires one, 1..80 characters).
+_ACTION_DETAILS = {"operator-decision-required": "no-decision", "decision-invalid": "invalid-decision",
+                   "human-step-required": "human-step", "approval-required": "no-approval"}
 
 _B64URL = re.compile(r"^[A-Za-z0-9_-]+\Z")
 # DL-2's grammar, as the contract's verifier types the claims (DEC-0045): an agent id, an opaque session or task id,
@@ -292,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)
 
@@ -801,11 +803,33 @@ def refusal_from_denial(denial: Dict[str, Any]) -> Dict[str, Any]:
     return {"error": error}
 
 
+def refusal_from_action(answer: Any) -> Optional[Dict[str, Any]]:
+    """DL-19 (DEC-0121): the refusal a service answers for an action call that fabric_actions.action_decision refused,
+    or None when it took the call. operator-decision-required, decision-invalid and approval-required carry their
+    detail; human-step-required carries `humanStep` and `url` (AP-4). A `fault` is the service's own and is never
+    sent: the caller reads unknown-state with the detail `service-fault`, as for anything else that is not an answer."""
+    if isinstance(answer, dict) and answer.get("ok") is True:
+        return None
+    code = answer.get("code") if isinstance(answer, dict) and answer.get("ok") is False else None
+    if not isinstance(code, str) or code not in _ACTION_DETAILS:
+        return _refuse("unknown-state", "service-fault")
+    data = answer.get("data")
+    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]: