auth51-governance 0.1.0__tar.gz

auth51_governance-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+# Publishes on a GitHub Release. Uses PyPI Trusted Publishing (OIDC) — no stored
+# API token. Configure the trusted publisher on PyPI first: project auth51-governance
+# → publisher = this repo, workflow "publish.yml", environment "pypi".
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Job-level permissions REPLACE the workflow-level block (not merged), so
+      # both must be listed here or checkout 404s on a private repo.
+      contents: read    # let actions/checkout read the (private) repo
+      id-token: write   # mint the OIDC token PyPI verifies (no stored secret)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

auth51_governance-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.DS_Store

auth51_governance-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.5
+Name: auth51-governance
+Version: 0.1.0
+Summary: The auth51 governance engine — classify action consequence into tiers, synthesize guarded workflows from observed runs, and validate a proposed workflow against the tier floor at registration.
+Project-URL: Homepage, https://auth51.com
+Project-URL: Repository, https://github.com/unforge-io/auth51-governance
+Author-email: unforge <dev-admin@unforge.io>
+License: Apache-2.0
+Keywords: agentic-authorization,ai-agents,auth51,governance,workflow
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# auth51-governance
+
+The governance-time engine for auth51. It does three things, all pure and stdlib-only:
+
+1. **Classify** an action's consequence into an ordered tier
+   (`READ < WRITE < SENSITIVE < FINANCIAL < DESTRUCTIVE`).
+2. **Synthesize** a guarded workflow from sampled run observations plus the roster's
+   capability catalog. Guard *strength* follows the tier, not a single boolean.
+3. **Validate** a proposed workflow against the tier floor, so the authority can reject
+   a workflow that frees a dangerous capability regardless of who proposed it.
+
+## Why it's a separate library
+
+Deriving and registering workflows is a **governance-time** act, not a runtime one —
+even though the learning signal (observations) comes from runs. Any client can produce
+observations: the reference workforce, a custom app on the auth51 client, or the
+auth51d gateway. They all feed the same engine here, and the authority stays the single
+source of truth for guard strength by calling `validate_workflow` at registration.
+
+Kept dependency-light and portable, exactly like `auth51-checksum`, so both the
+authority and clients can depend on it without pulling a framework.
+
+## The guard ladder
+
+|             | observed (≥ `min_support` runs)            | unobserved / under-supported |
+|-------------|--------------------------------------------|------------------------------|
+| READ        | free                                       | (no step)                    |
+| WRITE       | free                                       | (no step)                    |
+| SENSITIVE   | ordered (must follow legit predecessors)   | approval gate                |
+| FINANCIAL   | ordered (value-bound in a later phase)     | approval gate                |
+| DESTRUCTIVE | approval gate (never downgraded)           | approval gate                |
+
+Two properties over the old binary model: a real ladder (an identity edit ≠ a money
+movement), and high tiers never auto-free (a DESTRUCTIVE op seen once still needs a
+human; a FINANCIAL op is never free).
+
+## Usage
+
+```python
+from auth51_governance import (
+    Capability, obs_from_spans, synthesize, validate_workflow, ConsequenceTier,
+)
+
+# what the roster CAN do (classified from spec risk/tags, else the name)
+caps = [
+    Capability.classify("refunder", "RetrieveCustomer"),
+    Capability.classify("refunder", "CreatePayout", risk="financial"),
+    Capability.classify("admin", "DropDatabase"),
+]
+
+# what runs DID (from each run's spans)
+runs = [obs_from_spans(spans) for spans in sampled_runs]
+
+wf = synthesize("refund-flow", runs, caps)          # a guarded WorkflowDefinition dict
+
+# at the authority, before registering:
+violations = validate_workflow(wf, tier_of=lambda a, act: my_registry_tier(a, act))
+assert not violations
+```
+
+## Compiles down to the authority's step primitives
+
+`synthesize` emits the same `WorkflowStep` shape the authority already enforces:
+`dependencies` (ordering), `scopes` (subset), and an approval-gate step. Each step also
+carries a `tier` annotation the authority stores and the value-binding phase will use.

auth51_governance-0.1.0/README.md

@@ -0,0 +1,65 @@
+# auth51-governance
+
+The governance-time engine for auth51. It does three things, all pure and stdlib-only:
+
+1. **Classify** an action's consequence into an ordered tier
+   (`READ < WRITE < SENSITIVE < FINANCIAL < DESTRUCTIVE`).
+2. **Synthesize** a guarded workflow from sampled run observations plus the roster's
+   capability catalog. Guard *strength* follows the tier, not a single boolean.
+3. **Validate** a proposed workflow against the tier floor, so the authority can reject
+   a workflow that frees a dangerous capability regardless of who proposed it.
+
+## Why it's a separate library
+
+Deriving and registering workflows is a **governance-time** act, not a runtime one —
+even though the learning signal (observations) comes from runs. Any client can produce
+observations: the reference workforce, a custom app on the auth51 client, or the
+auth51d gateway. They all feed the same engine here, and the authority stays the single
+source of truth for guard strength by calling `validate_workflow` at registration.
+
+Kept dependency-light and portable, exactly like `auth51-checksum`, so both the
+authority and clients can depend on it without pulling a framework.
+
+## The guard ladder
+
+|             | observed (≥ `min_support` runs)            | unobserved / under-supported |
+|-------------|--------------------------------------------|------------------------------|
+| READ        | free                                       | (no step)                    |
+| WRITE       | free                                       | (no step)                    |
+| SENSITIVE   | ordered (must follow legit predecessors)   | approval gate                |
+| FINANCIAL   | ordered (value-bound in a later phase)     | approval gate                |
+| DESTRUCTIVE | approval gate (never downgraded)           | approval gate                |
+
+Two properties over the old binary model: a real ladder (an identity edit ≠ a money
+movement), and high tiers never auto-free (a DESTRUCTIVE op seen once still needs a
+human; a FINANCIAL op is never free).
+
+## Usage
+
+```python
+from auth51_governance import (
+    Capability, obs_from_spans, synthesize, validate_workflow, ConsequenceTier,
+)
+
+# what the roster CAN do (classified from spec risk/tags, else the name)
+caps = [
+    Capability.classify("refunder", "RetrieveCustomer"),
+    Capability.classify("refunder", "CreatePayout", risk="financial"),
+    Capability.classify("admin", "DropDatabase"),
+]
+
+# what runs DID (from each run's spans)
+runs = [obs_from_spans(spans) for spans in sampled_runs]
+
+wf = synthesize("refund-flow", runs, caps)          # a guarded WorkflowDefinition dict
+
+# at the authority, before registering:
+violations = validate_workflow(wf, tier_of=lambda a, act: my_registry_tier(a, act))
+assert not violations
+```
+
+## Compiles down to the authority's step primitives
+
+`synthesize` emits the same `WorkflowStep` shape the authority already enforces:
+`dependencies` (ordering), `scopes` (subset), and an approval-gate step. Each step also
+carries a `tier` annotation the authority stores and the value-binding phase will use.

auth51_governance-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "auth51-governance"
+version = "0.1.0"
+description = "The auth51 governance engine — classify action consequence into tiers, synthesize guarded workflows from observed runs, and validate a proposed workflow against the tier floor at registration."
+authors = [{ name = "unforge", email = "dev-admin@unforge.io" }]
+license = { text = "Apache-2.0" }
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []                       # stdlib only — this must be trivially portable
+keywords = ["auth51", "agentic-authorization", "workflow", "governance", "ai-agents"]
+classifiers = [
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+    "Topic :: Security",
+]
+
+[project.urls]
+Homepage = "https://auth51.com"
+Repository = "https://github.com/unforge-io/auth51-governance"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/auth51_governance"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

auth51_governance-0.1.0/src/auth51_governance/__init__.py

@@ -0,0 +1,55 @@
+"""
+auth51-governance — the governance-time engine that turns observed runs into guarded
+workflows, and validates a proposed workflow against the consequence-tier floor.
+
+ONE engine, used on both sides of the trust boundary:
+  * a client (or CI, or the console) DERIVES a proposal from sampled observations;
+  * the authority VALIDATES the submitted workflow against its own policy before
+    registering it.
+
+Tiers are OPEN (data — a configurable :class:`TierPolicy`); enforcement primitives are
+CLOSED (:class:`GuardStrength`, what the authority can enforce). Every tier resolves to
+a guard strength, so an enterprise can define its own tiers without ever meaning
+something the enforcer can't honour.
+
+Deriving/registering workflows is a governance-time act, not a runtime one — even
+though the learning signal (observations) comes from runs. Keeping the engine here, as
+a dependency-light shared library (like auth51-checksum), lets any client — the
+reference workforce, a custom app on the auth51 client, or the auth51d gateway — derive
+identically while the authority stays the single source of truth. Stdlib-only.
+"""
+from .model import (
+    APPROVAL_ACTION,
+    APPROVAL_STEP,
+    APPROVER_AGENT,
+    Capability,
+    Key,
+    Obs,
+)
+from .observe import obs_from_spans
+from .policy import (
+    DEFAULT_POLICY,
+    EvidenceState,
+    GuardStrength,
+    TierPolicy,
+    TierRule,
+    classify_consequence,
+    is_high_consequence,
+    strength_rank,
+)
+from .synthesize import synthesize
+from .validate import TierLookup, step_strength, validate_workflow
+
+__all__ = [
+    # policy model
+    "TierPolicy", "TierRule", "GuardStrength", "EvidenceState",
+    "DEFAULT_POLICY", "classify_consequence", "is_high_consequence", "strength_rank",
+    # value types
+    "Obs", "Capability", "Key",
+    "APPROVAL_STEP", "APPROVER_AGENT", "APPROVAL_ACTION",
+    # engine
+    "obs_from_spans", "synthesize",
+    "validate_workflow", "step_strength", "TierLookup",
+]
+
+__version__ = "0.1.0"

auth51_governance-0.1.0/src/auth51_governance/model.py

@@ -0,0 +1,58 @@
+"""
+Neutral value types shared across the governance engine.
+
+``Obs`` is what a run DID (one governed step). ``Capability`` is what the roster CAN
+do (the full catalog, each tagged with its tier NAME under some policy). Both are
+framework-agnostic: no OpenTelemetry, no LangChain, no HTTP. A client adapts its own
+stores into these, and the engine consumes only these — that is what keeps derivation
+client-agnostic.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence, Tuple
+
+from .policy import DEFAULT_POLICY, TierPolicy
+
+Key = Tuple[str, str]  # (agent, action)
+
+# The synthetic human-approval step shared by every red line in a workflow.
+APPROVAL_STEP = "approval"
+APPROVER_AGENT = "human-approver"
+APPROVAL_ACTION = "ApproveHighConsequence"
+
+
+@dataclass(frozen=True)
+class Obs:
+    """One governed step observed in a run: an agent performing an action, in order."""
+
+    agent: str
+    action: str
+    scopes: Tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class Capability:
+    """An ``(agent, action)`` the roster CAN perform, with its consequence-tier NAME —
+    the full catalog, so a dangerous capability NEVER seen in a legit run is still
+    guarded (the red line is enumerated from what the agent COULD do, not only did).
+
+    ``tier`` is a name under the governing :class:`~auth51_governance.policy.TierPolicy`
+    (tiers are open, so this is a string, not a fixed enum)."""
+
+    agent: str
+    action: str
+    scopes: Tuple[str, ...] = ()
+    tier: str = "WRITE"
+
+    @classmethod
+    def classify(
+        cls, agent: str, action: str, scopes: Sequence[str] = (),
+        tags: Sequence[str] = (), risk: str = "",
+        *, policy: TierPolicy = DEFAULT_POLICY,
+    ) -> "Capability":
+        """Build a capability, classifying its tier from spec risk/tags then name under
+        ``policy``. The one place call sites should construct a capability from raw
+        surface data."""
+        return cls(agent, action, tuple(scopes),
+                   policy.classify(action, tags, risk))

auth51_governance-0.1.0/src/auth51_governance/observe.py

@@ -0,0 +1,33 @@
+"""
+Trace → observations adapter.
+
+The auth51 span format is a client contract: a governed tool call is a ``tool <name>``
+span carrying ``auth51.tool`` (the action / operationId) and ``auth51.agent_id`` (the
+acting agent). Any client that emits spans in that shape — the reference workforce, a
+custom app on the auth51 client, or the auth51d gateway — produces observations the
+engine can consume. This is the one place that knows the span shape; everything
+downstream sees only :class:`Obs`.
+"""
+from __future__ import annotations
+
+from typing import List, Sequence
+
+from .model import Obs
+
+
+def obs_from_spans(spans: Sequence[dict]) -> List[Obs]:
+    """Extract the ordered governed steps from ONE run's spans (already ordered by
+    start time). Mint/dpop/rs spans are skipped — they nest under the tool span."""
+    out: List[Obs] = []
+    for s in spans:
+        if not str(s.get("name") or "").startswith("tool "):
+            continue
+        attrs = s.get("attributes") or {}
+        action = attrs.get("auth51.tool")
+        agent = attrs.get("auth51.agent_id")
+        if action and agent:
+            scopes = attrs.get("auth51.scopes") or ()
+            if isinstance(scopes, str):
+                scopes = tuple(x for x in scopes.replace(",", " ").split() if x)
+            out.append(Obs(agent=str(agent), action=str(action), scopes=tuple(scopes)))
+    return out

auth51_governance-0.1.0/src/auth51_governance/policy.py

@@ -0,0 +1,292 @@
+"""
+Consequence-tier POLICY — the configurable risk model.
+
+Tiers are open; enforcement primitives are closed. A tier is just data (a name, a
+rank, classification rules, and a handler mapping evidence → guard strength). An
+enterprise may define any tiers it wants, order them, and wire each to a guard. What it
+cannot invent is a new ENFORCEMENT mechanism: every tier must resolve to a
+:class:`GuardStrength` the Authority actually implements. That is what keeps derivation
+and enforcement coherent — a tier can never mean something the enforcer doesn't
+understand.
+
+The policy is authority-owned config: :data:`DEFAULT_POLICY` ships, an enterprise
+overrides per org/app, and it serializes (:meth:`TierPolicy.to_dict`) so a client
+derives against the same policy it will be validated against. Stdlib-only.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Optional, Sequence, Tuple
+
+
+class GuardStrength(str, Enum):
+    """The CLOSED set of enforcement primitives. A tier's handler may only choose from
+    these; the Authority has enforcement code for each. Ordered by restrictiveness."""
+
+    FREE = "free"                # no guard — allowed
+    ORDERED = "ordered"          # must follow its legit predecessors (+ scope subset)
+    VALUE_BOUND = "value_bound"  # reserved: allowed only within derived value bounds (phase 3)
+    APPROVAL = "approval"        # a human approval gate must complete first (a red line)
+    # An EXTERNAL primitive (delegate to a configured PDP) is the future escape hatch
+    # for enterprise-specific logic — a product capability, not free-form config.
+
+
+_STRENGTH_RANK: Dict[GuardStrength, int] = {
+    GuardStrength.FREE: 0,
+    GuardStrength.ORDERED: 1,
+    GuardStrength.VALUE_BOUND: 2,
+    GuardStrength.APPROVAL: 3,
+}
+
+
+def strength_rank(g: GuardStrength) -> int:
+    return _STRENGTH_RANK[g]
+
+
+class EvidenceState(str, Enum):
+    """How much clean evidence a capability has, which the handler branches on."""
+
+    UNOBSERVED = "unobserved"                    # never seen in a clean run
+    OBSERVED_UNTRUSTED = "observed_untrusted"    # seen, but below min_support
+    OBSERVED_TRUSTED = "observed_trusted"        # seen in >= min_support runs
+
+
+@dataclass
+class TierRule:
+    """One tier: a name, a rank (ordering; higher = more consequential), a handler
+    (``guards``: evidence → guard strength), an enforcement ``floor`` (the minimum the
+    Authority accepts for any step of this tier), and classification rules."""
+
+    name: str
+    rank: int
+    guards: Dict[EvidenceState, GuardStrength]
+    floor: GuardStrength = GuardStrength.FREE
+    risk_values: Tuple[str, ...] = ()      # spec risk strings that map to this tier
+    tags: Tuple[str, ...] = ()             # tags that classify to this tier
+    name_patterns: Tuple[str, ...] = ()    # regex strings matched on the action name
+
+    def guard(self, evidence: EvidenceState) -> GuardStrength:
+        return self.guards.get(evidence, self.floor)
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "rank": self.rank,
+            "guards": {k.value: v.value for k, v in self.guards.items()},
+            "floor": self.floor.value,
+            "risk_values": list(self.risk_values),
+            "tags": list(self.tags),
+            "name_patterns": list(self.name_patterns),
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "TierRule":
+        return cls(
+            name=str(d["name"]),
+            rank=int(d.get("rank", 0)),
+            guards={EvidenceState(k): GuardStrength(v)
+                    for k, v in (d.get("guards") or {}).items()},
+            floor=GuardStrength(d.get("floor", "free")),
+            risk_values=tuple(d.get("risk_values") or ()),
+            tags=tuple(d.get("tags") or ()),
+            name_patterns=tuple(d.get("name_patterns") or ()),
+        )
+
+
+_DEFAULT_READ_PATTERN = r"^(list|get|retrieve|describe|read|fetch|search|view|count|query|lookup)"
+
+
+@dataclass
+class TierPolicy:
+    """An ordered set of tiers plus the classification defaults. The source of truth for
+    guard strength; derivation and register-time validation both consume it."""
+
+    tiers: List[TierRule]
+    default_tier: str = "READ"
+    read_pattern: str = _DEFAULT_READ_PATTERN
+    min_support: int = 1
+
+    def __post_init__(self) -> None:
+        self._by_name: Dict[str, TierRule] = {t.name: t for t in self.tiers}
+        self._compiled: Dict[str, List[re.Pattern]] = {
+            t.name: [re.compile(p, re.IGNORECASE) for p in t.name_patterns]
+            for t in self.tiers
+        }
+        self._read_re = re.compile(self.read_pattern, re.IGNORECASE)
+
+    # ── lookups ──
+    def tier(self, name: str) -> Optional[TierRule]:
+        return self._by_name.get(name)
+
+    def rank_of(self, name: str) -> int:
+        t = self._by_name.get(name)
+        return t.rank if t else -1
+
+    def guard_for(self, name: str, evidence: EvidenceState) -> GuardStrength:
+        t = self._by_name.get(name)
+        return t.guard(evidence) if t else GuardStrength.FREE
+
+    def floor_for(self, name: str) -> GuardStrength:
+        t = self._by_name.get(name)
+        return t.floor if t else GuardStrength.FREE
+
+    # ── classification ──
+    def classify(self, action: str, tags: Sequence[str] = (), risk: str = "") -> str:
+        """Classify an action into a tier NAME. Precedence: an explicit spec ``risk``
+        value is authoritative; otherwise the highest-ranked tier whose tags match, or
+        (for a non-read name) whose name pattern matches. A read-verb name is classified
+        only by tags/risk, so ``ListPayouts`` stays READ unless a tag/risk raises it."""
+        rl = (risk or "").strip().lower()
+        if rl:
+            for t in self.tiers:
+                if rl in t.risk_values:
+                    return t.name
+        tagset = {(x or "").strip().lower() for x in (tags or ())}
+        is_read = bool(self._read_re.search(action or ""))
+        best: Optional[TierRule] = None
+        for t in self.tiers:
+            matched = bool(tagset & set(t.tags))
+            if not matched and not is_read:
+                matched = any(p.search(action or "") for p in self._compiled[t.name])
+            if matched and (best is None or t.rank > best.rank):
+                best = t
+        return best.name if best else self.default_tier
+
+    def is_red_line_tier(self, name: str) -> bool:
+        """Whether this tier is ever a red line (its handler can require approval, or its
+        floor is above ORDERED) — used by the back-compat boolean shim."""
+        t = self._by_name.get(name)
+        if t is None:
+            return False
+        strengths = list(t.guards.values()) + [t.floor]
+        return any(strength_rank(g) >= strength_rank(GuardStrength.APPROVAL)
+                   for g in strengths)
+
+    # ── serialization ──
+    def to_dict(self) -> dict:
+        return {
+            "default_tier": self.default_tier,
+            "read_pattern": self.read_pattern,
+            "min_support": self.min_support,
+            "tiers": [t.to_dict() for t in self.tiers],
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "TierPolicy":
+        return cls(
+            tiers=[TierRule.from_dict(t) for t in (d.get("tiers") or ())],
+            default_tier=str(d.get("default_tier", "READ")),
+            read_pattern=str(d.get("read_pattern", _DEFAULT_READ_PATTERN)),
+            min_support=int(d.get("min_support", 1)),
+        )
+
+
+# ── the default policy (ranks gapped by 10 so custom tiers can slot between) ──
+_ALL_EVIDENCE = (
+    EvidenceState.UNOBSERVED,
+    EvidenceState.OBSERVED_UNTRUSTED,
+    EvidenceState.OBSERVED_TRUSTED,
+)
+
+
+def _all(g: GuardStrength) -> Dict[EvidenceState, GuardStrength]:
+    return {e: g for e in _ALL_EVIDENCE}
+
+
+def _red_line_unless_trusted(trusted: GuardStrength) -> Dict[EvidenceState, GuardStrength]:
+    """Approval until there's enough clean evidence, then downgrade to ``trusted``."""
+    return {
+        EvidenceState.UNOBSERVED: GuardStrength.APPROVAL,
+        EvidenceState.OBSERVED_UNTRUSTED: GuardStrength.APPROVAL,
+        EvidenceState.OBSERVED_TRUSTED: trusted,
+    }
+
+
+DEFAULT_POLICY = TierPolicy(
+    default_tier="READ",
+    tiers=[
+        TierRule(
+            name="READ", rank=0, guards=_all(GuardStrength.FREE),
+            floor=GuardStrength.FREE,
+            risk_values=("read", "none", "safe"),
+            tags=("read", "readonly", "none", "safe"),
+        ),
+        TierRule(
+            name="WRITE", rank=10, guards=_all(GuardStrength.FREE),
+            floor=GuardStrength.FREE,
+            risk_values=("write", "low", "medium"),
+            tags=("write", "mutation", "low", "medium"),
+            name_patterns=(r"(create|update|modify|edit|change|patch|replace|add|set|write|post|upsert)",),
+        ),
+        TierRule(
+            name="SENSITIVE", rank=20,
+            guards=_red_line_unless_trusted(GuardStrength.ORDERED),
+            floor=GuardStrength.FREE,
+            risk_values=("sensitive", "high"),
+            tags=("sensitive", "pii", "account", "identity", "high"),
+            name_patterns=(
+                r"(create|update|modify|edit|change|patch|replace|add|set)[a-z0-9_]*?"
+                r"(customer|account|user|member|owner|role|permission|policy|credential|"
+                r"secret|apikey|api_key|token|password|email|phone|address|profile)",
+                r"(customer|account|user|member|owner|role|permission|policy|credential|"
+                r"secret|token|email|phone|address|profile)[a-z0-9_]*?"
+                r"(create|update|modify|edit|change|patch|replace|add|set)",
+            ),
+        ),
+        TierRule(
+            name="FINANCIAL", rank=30,
+            guards=_red_line_unless_trusted(GuardStrength.ORDERED),  # VALUE_BOUND in phase 3
+            floor=GuardStrength.ORDERED,
+            risk_values=("financial", "payment"),
+            tags=("financial", "payment", "payout", "money", "billing", "funds"),
+            name_patterns=(
+                r"(payout|transfer|refund|charge|payment|withdraw|deposit|settle|"
+                r"capture|disburse|remit|invoice|chargeback|topup|top_up)",
+            ),
+        ),
+        TierRule(
+            name="SECURITY", rank=40, guards=_all(GuardStrength.APPROVAL),
+            floor=GuardStrength.APPROVAL,
+            risk_values=("security",),
+            tags=("security", "iam", "privilege", "admin", "access"),
+            name_patterns=(
+                r"(attach|detach|put|set|create|update|delete)?[a-z0-9_]*polic",
+                r"grant[a-z0-9_]*(role|permission|access|scope)",
+                r"(revoke|escalat|assumerole|impersonat)",
+                r"(disable|enable)[a-z0-9_]*mfa",
+                r"(rotate|disable)[a-z0-9_]*(key|credential|secret)",
+                r"(add|remove)[a-z0-9_]*(admin|owner|member)",
+            ),
+        ),
+        TierRule(
+            name="DESTRUCTIVE", rank=50, guards=_all(GuardStrength.APPROVAL),
+            floor=GuardStrength.APPROVAL,
+            risk_values=("destructive", "critical"),
+            tags=("destructive", "delete"),
+            name_patterns=(
+                r"(drop|truncate|purge|destroy|wipe|erase|deprovision)",
+                r"delete[a-z0-9_]*(database|table|bucket|volume|cluster|instance|"
+                r"account|customer|user|record|data)",
+                r"terminate[a-z0-9_]*(instance|cluster|node)",
+            ),
+        ),
+    ],
+)
+
+
+def classify_consequence(
+    action: str, tags: Sequence[str] = (), risk: str = "",
+    *, policy: TierPolicy = DEFAULT_POLICY,
+) -> str:
+    """Classify one action into a tier name under ``policy`` (default: shipped policy)."""
+    return policy.classify(action, tags, risk)
+
+
+def is_high_consequence(
+    action: str, tags: Sequence[str] = (), risk: str = "",
+    *, policy: TierPolicy = DEFAULT_POLICY,
+) -> bool:
+    """Back-compat boolean: is this action's tier ever a red line under ``policy``?"""
+    return policy.is_red_line_tier(policy.classify(action, tags, risk))

auth51_governance-0.1.0/src/auth51_governance/synthesize.py

@@ -0,0 +1,190 @@
+"""
+Workflow synthesis from observed runs + the roster capability catalog.
+
+Concrete runs of a use case are INSTANCES; the workflow is the CLASS induced from
+them. We mine the observed ``(agent, action)`` steps and the partial order that holds
+across runs, then emit a GUARDED workflow whose guard STRENGTH is set by each
+capability's tier under the governing :class:`~auth51_governance.policy.TierPolicy` —
+not a single boolean, and not a fixed table.
+
+The tier's handler maps evidence (unobserved / observed-untrusted / observed-trusted)
+to a :class:`~auth51_governance.policy.GuardStrength`, which is then compiled to the
+authority's step primitives (``dependencies`` ordering, ``scopes`` subset, and an
+approval-gate step). Because guard strength comes from the policy, an enterprise can
+retune how strongly any tier is guarded without touching this code.
+
+Pure + store-agnostic. Enforce-first + guarded by default.
+"""
+from __future__ import annotations
+
+from typing import Dict, List, Sequence, Set, Tuple
+
+from .model import (
+    APPROVAL_ACTION,
+    APPROVAL_STEP,
+    APPROVER_AGENT,
+    Capability,
+    Key,
+    Obs,
+)
+from .policy import DEFAULT_POLICY, EvidenceState, GuardStrength, TierPolicy
+
+
+def _slug(s: str) -> str:
+    out = "".join(c if c.isalnum() else "_" for c in (s or "").strip().lower())
+    return out.strip("_") or "step"
+
+
+def synthesize(
+    workflow_id: str,
+    runs: Sequence[Sequence[Obs]],
+    capabilities: Sequence[Capability] = (),
+    *,
+    policy: TierPolicy = DEFAULT_POLICY,
+    mode: str = "enforce",
+    control: str = "guarded",
+    min_support: int | None = None,
+    approver_agent: str = APPROVER_AGENT,
+    approval_action: str = APPROVAL_ACTION,
+) -> dict:
+    """Return a ``WorkflowDefinition`` dict (the shape the Authority's
+    ``register/workflow`` accepts), guarded per ``policy``. ``min_support`` overrides the
+    policy's default: it is the run count a capability must reach to count as
+    OBSERVED_TRUSTED (below it, OBSERVED_UNTRUSTED — usually still a red line)."""
+    support_floor = policy.min_support if min_support is None else min_support
+
+    # ── observed steps, per-run first-occurrence index, cross-run support ──
+    observed: Dict[Key, Obs] = {}
+    run_first: List[Dict[Key, int]] = []
+    support: Dict[Key, int] = {}
+    for run in runs:
+        first: Dict[Key, int] = {}
+        for i, o in enumerate(run):
+            k = (o.agent, o.action)
+            observed.setdefault(k, o)
+            first.setdefault(k, i)
+        for k in first:
+            support[k] = support.get(k, 0) + 1
+        run_first.append(first)
+
+    keys = list(observed)
+    n = len(runs)
+
+    # ── always-before: A precedes B in EVERY run where both occur (>= 1 such run) ──
+    def always_before(a: Key, b: Key) -> bool:
+        seen_together = False
+        for first in run_first:
+            if a in first and b in first:
+                seen_together = True
+                if not first[a] < first[b]:
+                    return False
+        return seen_together
+
+    preds: Dict[Key, Set[Key]] = {
+        b: {a for a in keys if a != b and always_before(a, b)} for b in keys
+    }
+
+    tier_of: Dict[Key, str] = {(c.agent, c.action): c.tier for c in capabilities}
+    cap_scopes: Dict[Key, Tuple[str, ...]] = {
+        (c.agent, c.action): c.scopes for c in capabilities
+    }
+
+    # ── stable, unique step names ──
+    used: Set[str] = set()
+    name_of: Dict[Key, str] = {}
+
+    def _name(agent: str, action: str) -> str:
+        base = _slug(action)
+        name = base if base not in used else f"{base}__{_slug(agent)}"
+        while name in used:
+            name += "_x"
+        used.add(name)
+        return name
+
+    for agent, action in keys:
+        name_of[(agent, action)] = _name(agent, action)
+
+    def required(k: Key) -> bool:
+        return n > 0 and all(k in first for first in run_first)
+
+    def evidence_of(k: Key, *, observed_flag: bool) -> EvidenceState:
+        if not observed_flag:
+            return EvidenceState.UNOBSERVED
+        return (EvidenceState.OBSERVED_TRUSTED
+                if support.get(k, 0) >= support_floor
+                else EvidenceState.OBSERVED_UNTRUSTED)
+
+    steps: Dict[str, dict] = {}
+    need_approval = False
+
+    def _emit(k: Key, *, agent: str, action: str, tier: str,
+              strength: GuardStrength, scopes: Sequence[str], is_required: bool) -> None:
+        nonlocal need_approval
+        deps = sorted(name_of[p] for p in preds.get(k, ()))  # legit predecessors
+        value_bound = False
+        if strength is GuardStrength.FREE:
+            dependencies: List[str] = []
+        elif strength is GuardStrength.ORDERED:
+            dependencies = deps
+        elif strength is GuardStrength.VALUE_BOUND:
+            # Reserved (phase 3): ordering today, plus a marker the value-binding phase
+            # and register-time validation recognise. Enforced as ORDERED until then.
+            dependencies = deps
+            value_bound = True
+        else:  # APPROVAL — a human gate must complete first (plus any legit order)
+            dependencies = sorted(set(deps) | {APPROVAL_STEP})
+            need_approval = True
+        step = {
+            "agent": agent,
+            "action": action,
+            "scopes": list(scopes),
+            "dependencies": dependencies,
+            "required": is_required,
+            "approval_gate": False,
+            "requires_approval": False,
+            "tier": tier,
+        }
+        if value_bound:
+            step["value_bound"] = True
+        steps[name_of[k]] = step
+
+    # Observed steps = the full class. Guard strength follows the tier + evidence.
+    for k in keys:
+        agent, action = k
+        tier = tier_of.get(k, policy.default_tier)
+        strength = policy.guard_for(tier, evidence_of(k, observed_flag=True))
+        _emit(k, agent=agent, action=action, tier=tier, strength=strength,
+              scopes=(observed[k].scopes or cap_scopes.get(k, ())),
+              is_required=required(k))
+
+    # Unobserved capabilities: a red line when the tier guards them above FREE; low
+    # tiers stay FREE and un-emitted so the guard set stays sparse (govern the boundary).
+    for c in capabilities:
+        k = (c.agent, c.action)
+        if k in observed:
+            continue
+        strength = policy.guard_for(c.tier, EvidenceState.UNOBSERVED)
+        if strength is GuardStrength.FREE:
+            continue
+        name_of.setdefault(k, _name(c.agent, c.action))
+        _emit(k, agent=c.agent, action=c.action, tier=c.tier, strength=strength,
+              scopes=c.scopes, is_required=False)
+
+    if need_approval:
+        steps[APPROVAL_STEP] = {
+            "agent": approver_agent,
+            "action": approval_action,
+            "scopes": [],
+            "dependencies": [],
+            "required": False,
+            "approval_gate": True,
+            "requires_approval": False,
+        }
+
+    return {
+        "workflow_id": workflow_id,
+        "workflow_type": "dag",
+        "mode": mode,
+        "control": control,
+        "steps": steps,
+    }

auth51_governance-0.1.0/src/auth51_governance/validate.py

@@ -0,0 +1,63 @@
+"""
+Register-time workflow validation — the trust boundary.
+
+Derivation is a PROPOSAL and can run anywhere: a client's local dry-run, a CI job, or
+the console. Because a client is replaceable and untrusted, the Authority must NOT trust
+a submitted workflow's guards. It re-checks, against its OWN policy and its stored tier
+per capability, that each step's guard strength meets the tier's ``floor``. This is not
+a re-derive (the Authority has no traces); it is a floor check.
+
+A capability whose tier the Authority does not know is skipped (it can only enforce the
+floor for capabilities it has classified). Same posture as mint: the client may PROPOSE
+anything; the Authority decides what may register.
+"""
+from __future__ import annotations
+
+from typing import Callable, List, Optional
+
+from .policy import (
+    DEFAULT_POLICY,
+    GuardStrength,
+    TierPolicy,
+    strength_rank,
+)
+
+# (agent, action) -> tier name, or None when the Authority hasn't classified it.
+TierLookup = Callable[[str, str], Optional[str]]
+
+
+def step_strength(step: dict, approval_steps: set) -> GuardStrength:
+    """The guard strength a stored step actually carries, read from its fields."""
+    deps = set(step.get("dependencies") or [])
+    if step.get("requires_approval") or (deps & approval_steps):
+        return GuardStrength.APPROVAL
+    if step.get("value_bound"):
+        return GuardStrength.VALUE_BOUND
+    if deps:
+        return GuardStrength.ORDERED
+    return GuardStrength.FREE
+
+
+def validate_workflow(
+    workflow: dict, tier_of: TierLookup, *, policy: TierPolicy = DEFAULT_POLICY,
+) -> List[str]:
+    """Return a list of floor violations (empty = OK to register). ``tier_of`` maps an
+    ``(agent, action)`` to the Authority's stored tier name (or ``None`` if unknown)."""
+    steps = workflow.get("steps") or {}
+    approval_steps = {name for name, s in steps.items() if s.get("approval_gate")}
+    violations: List[str] = []
+
+    for name, s in steps.items():
+        if s.get("approval_gate"):
+            continue  # the gate itself is not a governed capability
+        tier = tier_of(s.get("agent", ""), s.get("action", ""))
+        if tier is None:
+            continue
+        floor = policy.floor_for(tier)
+        actual = step_strength(s, approval_steps)
+        if strength_rank(actual) < strength_rank(floor):
+            violations.append(
+                f"step '{name}' runs {tier} action '{s.get('action')}' at guard "
+                f"'{actual.value}', below the required floor '{floor.value}'")
+
+    return violations

auth51_governance-0.1.0/tests/test_policy.py

@@ -0,0 +1,100 @@
+"""The default policy: classification, precedence, the SECURITY tier, serialization,
+and — the point of the redesign — a fully custom enterprise policy."""
+from auth51_governance import (
+    DEFAULT_POLICY,
+    EvidenceState,
+    GuardStrength,
+    TierPolicy,
+    TierRule,
+    classify_consequence,
+    is_high_consequence,
+)
+
+c = classify_consequence
+
+
+def test_reads_are_read_tier():
+    for name in ("ListPayouts", "GetCustomer", "RetrieveCharge", "SearchTransfers",
+                 "describe_account", "query_ledger"):
+        assert c(name) == "READ", name
+
+
+def test_sensitive_nouns_lift_writes_to_sensitive():
+    assert c("UpdateCustomer") == "SENSITIVE"
+    assert c("SetUserRole") == "SENSITIVE"
+    assert c("AddTag") == "WRITE"
+    assert DEFAULT_POLICY.rank_of("UpdateCustomer" and c("UpdateCustomer")) < \
+        DEFAULT_POLICY.rank_of(c("CreatePayout"))
+
+
+def test_financial_and_destructive_and_security_tiers():
+    assert c("CreatePayout") == "FINANCIAL"
+    assert c("IssueRefund") == "FINANCIAL"
+    assert c("DropDatabase") == "DESTRUCTIVE"
+    assert c("DeleteCustomer") == "DESTRUCTIVE"
+    assert c("AttachRolePolicy") == "SECURITY"
+    assert c("RevokeAccess") == "SECURITY"
+    assert c("DisableMfa") == "SECURITY"
+
+
+def test_explicit_spec_risk_overrides_name_even_for_a_read_name():
+    assert c("GetPayoutNow", risk="financial") == "FINANCIAL"
+    assert c("RetrieveThing", risk="destructive") == "DESTRUCTIVE"
+    assert c("CreatePayout", risk="low") == "WRITE"          # spec can LOWER it too
+
+
+def test_tags_raise_a_read_name():
+    assert c("ListThings") == "READ"
+    assert c("ListThings", tags=["financial"]) == "FINANCIAL"
+    assert c("GetThing", tags=["destructive"]) == "DESTRUCTIVE"
+
+
+def test_highest_rank_tier_wins():
+    # both WRITE (create) and FINANCIAL (payout) patterns match; the higher rank wins
+    assert c("CreatePayout") == "FINANCIAL"
+    assert c("DoThing", tags=["sensitive", "financial"]) == "FINANCIAL"
+
+
+def test_high_consequence_shim():
+    assert is_high_consequence("CreatePayout") is True
+    assert is_high_consequence("UpdateCustomer") is True
+    assert is_high_consequence("DropDatabase") is True
+    assert is_high_consequence("GetCustomer") is False
+    assert is_high_consequence("AddTag") is False
+
+
+def test_policy_serialization_roundtrip():
+    d = DEFAULT_POLICY.to_dict()
+    back = TierPolicy.from_dict(d)
+    for name in ("GetCustomer", "UpdateCustomer", "CreatePayout", "DropDatabase",
+                 "AttachRolePolicy"):
+        assert back.classify(name) == DEFAULT_POLICY.classify(name), name
+    assert back.floor_for("FINANCIAL") == GuardStrength.ORDERED
+    assert back.floor_for("DESTRUCTIVE") == GuardStrength.APPROVAL
+
+
+def test_custom_enterprise_policy_defines_new_tiers():
+    """An enterprise can define entirely new tiers + handlers; the engine honours them
+    without any code change here — the flexibility the design promises."""
+    approval_all = {e: GuardStrength.APPROVAL for e in EvidenceState}
+    custom = TierPolicy(
+        default_tier="PUBLIC",
+        tiers=[
+            TierRule("PUBLIC", 0, {e: GuardStrength.FREE for e in EvidenceState},
+                     floor=GuardStrength.FREE),
+            TierRule("INTERNAL", 10, {e: GuardStrength.FREE for e in EvidenceState},
+                     floor=GuardStrength.FREE,
+                     name_patterns=(r"(create|update|set)",)),
+            TierRule("PHI_EXPORT", 90, approval_all, floor=GuardStrength.APPROVAL,
+                     tags=("phi", "health"),
+                     name_patterns=(r"(disclose|export)[a-z0-9_]*(record|patient|phi)",)),
+        ],
+    )
+    assert custom.classify("ExportPatientRecord") == "PHI_EXPORT"
+    assert custom.classify("DisclosePhi", tags=["health"]) == "PHI_EXPORT"
+    assert custom.classify("GetLedger") == "PUBLIC"          # falls to default
+    assert custom.classify("UpdateThing") == "INTERNAL"
+    # a new tier's floor is enforced exactly like a built-in one
+    assert custom.floor_for("PHI_EXPORT") == GuardStrength.APPROVAL
+    # and it roundtrips through serialization (so the authority can store it)
+    assert TierPolicy.from_dict(custom.to_dict()).classify("ExportPatientRecord") == "PHI_EXPORT"

auth51_governance-0.1.0/tests/test_synthesize.py

@@ -0,0 +1,129 @@
+"""The guard ladder in synthesis: tier + evidence → guard strength (policy-driven)."""
+from auth51_governance import (
+    APPROVAL_STEP,
+    Capability,
+    EvidenceState,
+    GuardStrength,
+    Obs,
+    TierPolicy,
+    TierRule,
+    synthesize,
+)
+
+
+def _cap(agent, action, tier, scopes=()):
+    return Capability(agent, action, tuple(scopes), tier)
+
+
+def _deps(wf, action):
+    for s in wf["steps"].values():
+        if s["action"] == action:
+            return set(s["dependencies"])
+    raise AssertionError(f"no step for {action}")
+
+
+def _step(wf, action):
+    for s in wf["steps"].values():
+        if s["action"] == action:
+            return s
+    raise AssertionError(action)
+
+
+def _has_step(wf, action):
+    return any(s["action"] == action for s in wf["steps"].values())
+
+
+def test_reproduces_stripe_refund_screenshot():
+    """The exact console case: 2 clean runs observed only RetrieveCustomer; the roster's
+    dangerous ops (never observed) become red lines behind approval."""
+    caps = [
+        _cap("refunder", "RetrieveCustomer", "READ"),
+        _cap("refunder", "UpdateCustomer", "SENSITIVE"),
+        _cap("refunder", "CreateExternalAccount", "FINANCIAL"),
+        _cap("refunder", "CreatePayout", "FINANCIAL"),
+        _cap("refunder", "CreateTransfer", "FINANCIAL"),
+    ]
+    runs = [[Obs("refunder", "RetrieveCustomer")],
+            [Obs("refunder", "RetrieveCustomer")]]
+    wf = synthesize("refund-flow", runs, caps)
+
+    assert _deps(wf, "RetrieveCustomer") == set()          # observed read → free
+    for action in ("UpdateCustomer", "CreateExternalAccount", "CreatePayout", "CreateTransfer"):
+        assert APPROVAL_STEP in _deps(wf, action), action  # unobserved red lines → approval
+    assert wf["steps"][APPROVAL_STEP]["approval_gate"] is True
+    assert wf["mode"] == "enforce" and wf["control"] == "guarded"
+
+
+def test_free_tiers_when_unobserved_emit_no_step():
+    caps = [
+        _cap("a", "GetThing", "READ"),
+        _cap("a", "AddTag", "WRITE"),
+        _cap("a", "CreatePayout", "FINANCIAL"),
+    ]
+    wf = synthesize("w", [], caps)
+    assert not _has_step(wf, "GetThing")
+    assert not _has_step(wf, "AddTag")
+    assert _has_step(wf, "CreatePayout")
+
+
+def test_observed_sensitive_is_ordered_not_approval():
+    caps = [_cap("a", "GetCase", "READ"), _cap("a", "UpdateCustomer", "SENSITIVE")]
+    runs = [[Obs("a", "GetCase"), Obs("a", "UpdateCustomer")]]
+    wf = synthesize("w", runs, caps)
+    deps = _deps(wf, "UpdateCustomer")
+    assert APPROVAL_STEP not in deps and "getcase" in deps
+
+
+def test_observed_financial_is_ordered_never_free():
+    caps = [_cap("a", "GetCase", "READ"), _cap("a", "IssueRefund", "FINANCIAL")]
+    runs = [[Obs("a", "GetCase"), Obs("a", "IssueRefund")]]
+    wf = synthesize("w", runs, caps)
+    assert _deps(wf, "IssueRefund") == {"getcase"}
+    assert _step(wf, "IssueRefund")["tier"] == "FINANCIAL"
+
+
+def test_destructive_is_approval_even_when_observed():
+    """#4 fix: a destructive op seen in clean runs still needs a human."""
+    caps = [_cap("a", "GetCase", "READ"), _cap("a", "DropDatabase", "DESTRUCTIVE")]
+    runs = [[Obs("a", "GetCase"), Obs("a", "DropDatabase")]] * 5
+    wf = synthesize("w", runs, caps)
+    assert APPROVAL_STEP in _deps(wf, "DropDatabase")
+
+
+def test_min_support_keeps_under_evidenced_financial_a_red_line():
+    caps = [_cap("a", "IssueRefund", "FINANCIAL")]
+    runs = [[Obs("a", "IssueRefund")]]
+    assert APPROVAL_STEP not in _deps(synthesize("w", runs, caps, min_support=1), "IssueRefund")
+    assert APPROVAL_STEP in _deps(synthesize("w", runs, caps, min_support=2), "IssueRefund")
+
+
+def test_step_shape_matches_authority_fields():
+    caps = [_cap("a", "CreatePayout", "FINANCIAL")]
+    wf = synthesize("w", [], caps)
+    step = _step(wf, "CreatePayout")
+    for key in ("agent", "action", "scopes", "dependencies", "required",
+                "approval_gate", "requires_approval", "tier"):
+        assert key in step, key
+
+
+def test_custom_policy_controls_guard_strength():
+    """A custom policy that value-binds an observed financial op instead of just
+    ordering it — synthesis honours the policy's handler without code changes here."""
+    policy = TierPolicy(
+        default_tier="READ",
+        tiers=[
+            TierRule("READ", 0, {e: GuardStrength.FREE for e in EvidenceState}),
+            TierRule("MONEY", 30, {
+                EvidenceState.UNOBSERVED: GuardStrength.APPROVAL,
+                EvidenceState.OBSERVED_UNTRUSTED: GuardStrength.APPROVAL,
+                EvidenceState.OBSERVED_TRUSTED: GuardStrength.VALUE_BOUND,
+            }, floor=GuardStrength.VALUE_BOUND, tags=("money",)),
+        ],
+    )
+    caps = [Capability("a", "GetCase", (), "READ"),
+            Capability("a", "SendMoney", (), "MONEY")]
+    runs = [[Obs("a", "GetCase"), Obs("a", "SendMoney")]]
+    wf = synthesize("w", runs, caps, policy=policy)
+    step = _step(wf, "SendMoney")
+    assert step["value_bound"] is True               # policy chose VALUE_BOUND
+    assert APPROVAL_STEP not in set(step["dependencies"])

auth51_governance-0.1.0/tests/test_validate.py

@@ -0,0 +1,75 @@
+"""Register-time floor: the authority rejects a workflow whose step guard is below the
+tier's floor, independent of who derived it."""
+from auth51_governance import Capability, Obs, synthesize, validate_workflow
+
+# The authority's stored tier per capability (names under its policy).
+_TIERS = {
+    ("a", "GetThing"): "READ",
+    ("a", "UpdateCustomer"): "SENSITIVE",
+    ("a", "CreatePayout"): "FINANCIAL",
+    ("a", "DropDatabase"): "DESTRUCTIVE",
+}
+
+
+def _tier_of(agent, action):
+    return _TIERS.get((agent, action))
+
+
+def test_synthesized_workflow_passes_its_own_floor():
+    caps = [Capability(a, act, (), t) for (a, act), t in _TIERS.items()]
+    wf = synthesize("w", [[Obs("a", "GetThing")]], caps)
+    assert validate_workflow(wf, _tier_of) == []
+
+
+def test_free_destructive_is_rejected():
+    wf = {"steps": {"drop": {"agent": "a", "action": "DropDatabase",
+                             "dependencies": [], "approval_gate": False,
+                             "requires_approval": False}}}
+    v = validate_workflow(wf, _tier_of)
+    assert len(v) == 1 and "DESTRUCTIVE" in v[0]
+
+
+def test_ordered_only_destructive_is_still_rejected():
+    wf = {"steps": {
+        "drop": {"agent": "a", "action": "DropDatabase", "dependencies": ["prep"]},
+        "prep": {"agent": "a", "action": "GetThing", "dependencies": []},
+    }}
+    assert validate_workflow(wf, _tier_of)          # ORDERED < APPROVAL floor
+
+
+def test_free_financial_rejected_but_ordered_passes():
+    free = {"steps": {"pay": {"agent": "a", "action": "CreatePayout",
+                              "dependencies": []}}}
+    ordered = {"steps": {
+        "pay": {"agent": "a", "action": "CreatePayout", "dependencies": ["prep"]},
+        "prep": {"agent": "a", "action": "GetThing", "dependencies": []},
+    }}
+    assert validate_workflow(free, _tier_of)
+    assert validate_workflow(ordered, _tier_of) == []
+
+
+def test_approval_gated_destructive_passes():
+    wf = {"steps": {
+        "drop": {"agent": "a", "action": "DropDatabase", "dependencies": ["approval"]},
+        "approval": {"agent": "human", "action": "Approve", "dependencies": [],
+                     "approval_gate": True},
+    }}
+    assert validate_workflow(wf, _tier_of) == []
+
+
+def test_requires_approval_flag_also_satisfies_the_gate():
+    wf = {"steps": {"drop": {"agent": "a", "action": "DropDatabase",
+                             "dependencies": [], "requires_approval": True}}}
+    assert validate_workflow(wf, _tier_of) == []
+
+
+def test_sensitive_free_is_allowed_by_default_floor():
+    # SENSITIVE's floor is FREE (recoverable); it's ordered by derivation, not mandated
+    wf = {"steps": {"upd": {"agent": "a", "action": "UpdateCustomer",
+                            "dependencies": []}}}
+    assert validate_workflow(wf, _tier_of) == []
+
+
+def test_unknown_capability_tier_is_skipped():
+    wf = {"steps": {"x": {"agent": "z", "action": "MysteryOp", "dependencies": []}}}
+    assert validate_workflow(wf, _tier_of) == []