frootai-orchard 1.0.0__tar.gz

frootai_orchard-1.0.0/.gitignore

@@ -0,0 +1,95 @@
+node_modules/
+website/build/
+website/.docusaurus/
+website/node_modules/
+npm-mcp/node_modules/
+.DS_Store
+*.log
+.env
+
+# [M8.18] Foundry deployment config — real values (subscription IDs, etc.)
+# stay local; only the .example template is committed.
+.frootai/foundry-config.json
+
+# [M9.11] Per-tenant ACA deployment params — same rationale.
+infra/hosted-mcp/aca.parameters.*.json
+!infra/hosted-mcp/aca.parameters.example.json
+# Pulumi state + tenant stacks
+infra/hosted-mcp/pulumi/Pulumi.*.yaml
+!infra/hosted-mcp/pulumi/Pulumi.yaml
+infra/hosted-mcp/pulumi/node_modules/
+infra/hosted-mcp/pulumi/bin/
+
+# [M9.14 / M9.15 / M9.16] k6 load-test results (per-run outputs, not committed).
+load-tests/hosted-mcp/last-run.json
+load-tests/hosted-mcp/last-run-federated.json
+load-tests/hosted-mcp/last-run-autoscale.json
+
+# [M9.20] Alpha-tenant onboarding — real configs hold subscription IDs.
+scripts/alpha-tenants.json
+scripts/alpha-tenants/
+
+# Test artefact + intermediate report directories — not source code.
+tmp/
+
+# Release-gate tarballs and AFCLI-T021 platform evidence are regenerated per run.
+artifacts/
+
+# Internal development plans — NOT pushed to remote
+.internal/
+
+# Website lives in separate private repo (frootai/frootai.dev)
+website/
+website-v2/
+website-v3/
+website-v4/
+website-v5/
+website-v6/
+website-implementation-plan.md
+
+__pycache__/
+*.pyc
+
+npm-sdk/node_modules/
+vscode-extension/esbuild.config.d.mts
+
+# FAI Factory — temp files (catalog is committed)
+.factory/harvest.json
+.factory/fai-catalog.prev.json
+.factory/changes.json
+.factory/logs/
+
+# Build artifacts (Phase 1 OT-3, May 3, 2026)
+# vsix bundles are produced by vsce-publish.yml; never commit
+*.vsix
+**/*.vsix
+# functions deploy.zip is produced by deploy-chatbot.yml; never commit
+
+# [X6.4] Cosign bundle-signing key material — NEVER commit the private key.
+# Generated by scripts/marketplace/sign/gen-key.mjs during the founder-only
+# key ceremony (docs/security/cosign-key-ceremony.md); stored in Vault.
+cosign.key
+*.key
+**/cosign.key
+functions/deploy.zip
+**/deploy.zip
+# Python build wheels & sdists are produced by pypi-publish.yml; never commit (Phase 2 cleanup, May 3, 2026)
+python-sdk/dist/
+python-mcp/dist/
+**/*.whl
+**/*.egg-info/
+.pytest_cache/
+**/.pytest_cache/
+
+# V0.3 avm-cache: per-module deep-fetched AVM source files (regenerable via npm run verified:catalog --deep-fetch)
+data/avm-cache/
+
+# [P1.1] Live telemetry ingest (real tenant data) — never commit; seed is the committed fallback
+observability/*.live.ndjson
+
+# 'public/' was an accidental submodule gitlink (no .gitmodules) that broke the
+# Cloudflare Workers Build clone (--recurse-submodules). Untracked + ignored.
+/public/
+
+# harvest service corpus (13MB build artifact, bundled into image not git)
+aca/frootai-harvest/corpus/

frootai_orchard-1.0.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to `frootai-orchard` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-05-26 (Phase A6.9–A6.16)
+
+> **Released under tag `orchard-v1.0.0`** (Phase A10 — General Availability). v1.0 additions:
+>
+> - **STABILITY.md** — explicit public-export list (`__all__` is the source of truth) + v1.x semver contract at `frootai-core/python-sdk/orchard/STABILITY.md` (inherits from repo-root `STABILITY.md`).
+> - **v1.0 semver promise** — every public symbol frozen until v2.0; 6-month minimum deprecation window.
+> - **Deprecation framework** at `frootai_orchard._deprecate` (`emit_deprecation`, `format_deprecation_line`); byte-equivalent with the npm peer at `@frootai/orchard-types/lib/deprecate`; opt-out via `FROOTAI_SUPPRESS_DEPRECATIONS=1`.
+
+> **Released under tag `orchard-v0.6.0-sdk`** (Phase A6 close — [retro](https://github.com/frootai/frootai-core/blob/main/planning/retros/orchard-phase6.md)). Ships with:
+>
+> - **PyPI trusted publishing** via OIDC (PEP 740 attestations — NO `PYPI_TOKEN` secret used). Audit via the PyPI JSON API: `https://pypi.org/pypi/frootai-orchard/1.0.0/json` → `urls[].provenance`
+> - **CycloneDX 1.5 SBOM** uploaded as 90-day workflow artifact (`orchard-sboms/orchard-py.sbom.json` — zero runtime deps so the SBOM lists only the root component)
+> - **Cross-SDK conformance certificate** uploaded as 90-day workflow artifact (SHA-256 manifest fingerprint, identical byte-for-byte contracts as `@frootai/orchard` v1.0.0)
+> - **Wheel size ≤ 100 KB** enforced as a publish gate (currently ~50 KB)
+
+Initial public release of the Python SDK. Byte-equal contract with the npm
+`@frootai/orchard` v1.0.0 SDK.
+
+### Added
+
+- `create_client(**opts)` — public client factory
+- `client.list(variety=, where=, limit=)` — iterator over catalog fruits
+- `client.search(query, where=, limit=)` — client-side scored search
+- `client.show(id)` — single fruit detail with index-scan fallback
+- `client.bushel.list/add/remove` — authenticated bushel sync (Team tier+)
+- `client.whoami()` — never-raises auth probe
+- `client.cursor.encode/decode` — opaque HMAC-signed pagination cursors
+- 10-class typed error hierarchy (`FrootaiOrchardError` + subclasses)
+- Filter expression language (`field:value AND/OR/NOT (...)`) byte-equal with npm
+- 3-tier cache (LRU 1k entries → disk `~/.frootai/cache/sdk/` 1h → network) with stale-while-error
+- Decorrelated-jitter retry + per-host circuit breaker + Retry-After honoring
+- Shared `~/.frootai/.token` auth file with the `frootai` CLI
+- `frootai_orchard._orchard_types` byte-equal mirror of `@frootai/orchard-types` v1.0.0

frootai_orchard-1.0.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.5
+Name: frootai-orchard
+Version: 1.0.0
+Summary: Programmatic SDK for the FrootAI Orchard catalog — type-safe list/search/show/bushel surface for partner apps, CI pipelines, and BI integrations. Reads the same ~/.frootai/.token + ~/.frootai/cache as the frootai CLI for transparent shared auth.
+Project-URL: Homepage, https://frootai.dev/orchard
+Project-URL: Repository, https://github.com/frootai/frootai-core
+Project-URL: Issues, https://github.com/frootai/frootai-core/issues
+Project-URL: Changelog, https://github.com/frootai/frootai-core/blob/main/python-sdk/orchard/CHANGELOG.md
+Author-email: FrootAI <hello@frootai.dev>
+License: MIT
+Keywords: accelerators,ai-agents,catalog,frootai,orchard,sdk,solution-plays
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# frootai-orchard
+
+Programmatic Python SDK for the FrootAI Orchard catalog — type-safe `list` / `search` / `show` / `bushel` surface for partner apps, CI pipelines, and BI integrations.
+
+Byte-equal contract with the npm `@frootai/orchard` v1.0.0 SDK: same enums, same filter expression language, same HMAC-signed pagination cursors, same retry semantics, same shared `~/.frootai/.token` auth file. A query that returns 12 results in JS returns the same 12 results in Python.
+
+## Install
+
+```bash
+pip install frootai-orchard
+```
+
+Zero runtime dependencies. Python 3.10+. Stdlib only (`urllib`, `hmac`, `base64`, `json`, `hashlib`, `pathlib`).
+
+## Quickstart
+
+```python
+from frootai_orchard import create_client
+
+client = create_client()
+
+# Anonymous catalog reads — no auth required
+for fruit in client.list(variety="azure", where="ripeness:Mature OR ripeness:Bearing"):
+    print(fruit["name"], "—", fruit.get("tagline", ""))
+
+# Search with scoring
+for hit in client.search("rag", limit=10):
+    print(f'{hit["_score"]:>2}  {hit["name"]}')
+
+# Single fruit detail
+detail = client.show("ms-azure-openai-rag")
+
+# Authenticated — bushel sync (Team tier+)
+client.bushel.add("ms-azure-openai-rag")
+print(client.bushel.list()["ids"])
+
+# Never-raises auth probe
+print(client.whoami())
+# → {"signed_in": True, "anonymous": False, "redacted": "…a3f9", ...}
+```
+
+## Auth priority
+
+1. `token=` keyword argument
+2. `FROOTAI_TOKEN` environment variable
+3. `~/.frootai/.token` shared file (same as the `frootai` CLI)
+
+A `frootai login` in your terminal transparently authorizes Python SDK calls.
+
+## Typed errors
+
+Every public surface raises only `FrootaiOrchardError` subclasses — partners catch by type, never by string match:
+
+```python
+from frootai_orchard import errors as fai_err
+
+try:
+    client.bushel.add("some-fruit")
+except fai_err.NotSignedInError:
+    print("Run `frootai login` first")
+except fai_err.EntitlementRequiredError as e:
+    print(f'Upgrade required: {e.context["entitlement"]}')
+except fai_err.RateLimitError as e:
+    print(f"Slow down — retry after {e.retry_after_ms} ms")
+```
+
+## Filter expression language
+
+Identical grammar to the npm SDK:
+
+```python
+client.list(where="tier_class:paid AND variety:azure")
+client.list(where="ripeness:Mature OR (variety:gcp AND category:rag)")
+client.list(where='NOT category:eval')
+```
+
+## License
+
+MIT

frootai_orchard-1.0.0/README.md

@@ -0,0 +1,79 @@
+# frootai-orchard
+
+Programmatic Python SDK for the FrootAI Orchard catalog — type-safe `list` / `search` / `show` / `bushel` surface for partner apps, CI pipelines, and BI integrations.
+
+Byte-equal contract with the npm `@frootai/orchard` v1.0.0 SDK: same enums, same filter expression language, same HMAC-signed pagination cursors, same retry semantics, same shared `~/.frootai/.token` auth file. A query that returns 12 results in JS returns the same 12 results in Python.
+
+## Install
+
+```bash
+pip install frootai-orchard
+```
+
+Zero runtime dependencies. Python 3.10+. Stdlib only (`urllib`, `hmac`, `base64`, `json`, `hashlib`, `pathlib`).
+
+## Quickstart
+
+```python
+from frootai_orchard import create_client
+
+client = create_client()
+
+# Anonymous catalog reads — no auth required
+for fruit in client.list(variety="azure", where="ripeness:Mature OR ripeness:Bearing"):
+    print(fruit["name"], "—", fruit.get("tagline", ""))
+
+# Search with scoring
+for hit in client.search("rag", limit=10):
+    print(f'{hit["_score"]:>2}  {hit["name"]}')
+
+# Single fruit detail
+detail = client.show("ms-azure-openai-rag")
+
+# Authenticated — bushel sync (Team tier+)
+client.bushel.add("ms-azure-openai-rag")
+print(client.bushel.list()["ids"])
+
+# Never-raises auth probe
+print(client.whoami())
+# → {"signed_in": True, "anonymous": False, "redacted": "…a3f9", ...}
+```
+
+## Auth priority
+
+1. `token=` keyword argument
+2. `FROOTAI_TOKEN` environment variable
+3. `~/.frootai/.token` shared file (same as the `frootai` CLI)
+
+A `frootai login` in your terminal transparently authorizes Python SDK calls.
+
+## Typed errors
+
+Every public surface raises only `FrootaiOrchardError` subclasses — partners catch by type, never by string match:
+
+```python
+from frootai_orchard import errors as fai_err
+
+try:
+    client.bushel.add("some-fruit")
+except fai_err.NotSignedInError:
+    print("Run `frootai login` first")
+except fai_err.EntitlementRequiredError as e:
+    print(f'Upgrade required: {e.context["entitlement"]}')
+except fai_err.RateLimitError as e:
+    print(f"Slow down — retry after {e.retry_after_ms} ms")
+```
+
+## Filter expression language
+
+Identical grammar to the npm SDK:
+
+```python
+client.list(where="tier_class:paid AND variety:azure")
+client.list(where="ripeness:Mature OR (variety:gcp AND category:rag)")
+client.list(where='NOT category:eval')
+```
+
+## License
+
+MIT

frootai_orchard-1.0.0/frootai_orchard/__init__.py

@@ -0,0 +1,73 @@
+"""
+frootai-orchard — public Python SDK for the FrootAI Orchard catalog.
+
+Usage:
+    from frootai_orchard import create_client
+    client = create_client()
+    for fruit in client.list(variety="azure"):
+        print(fruit["name"])
+
+Shared auth with the `frootai` CLI: reads `~/.frootai/.token` so a
+`frootai login` in your terminal transparently authorizes SDK calls.
+Override priority: `token=` arg > `FROOTAI_TOKEN` env > `~/.frootai/.token`.
+
+Mirror of the npm `@frootai/orchard` v1.0.0 SDK. Cross-language enum
+byte-equality enforced by the cross-SDK conformance test suite.
+"""
+
+from . import _orchard_types
+from . import auth, cache, cursor, errors, filter_lang, http_client
+from .client import create_client
+from .cursor import build_cursor_codec
+from .errors import (
+    AuthError,
+    ConflictError,
+    EntitlementRequiredError,
+    ERROR_CODES,
+    FrootaiOrchardError,
+    NetworkError,
+    NotFoundError,
+    NotSignedInError,
+    RateLimitError,
+    ServerError,
+    TokenExpiredError,
+    ValidationError,
+)
+from .filter_lang import build_predicate as build_filter_predicate
+from .filter_lang import parse as parse_filter
+
+__version__ = "1.0.0"
+VERSION = __version__
+
+__all__ = [
+    # Factory
+    "create_client",
+    # Error types (for isinstance checks at the call site)
+    "FrootaiOrchardError",
+    "AuthError",
+    "NotSignedInError",
+    "TokenExpiredError",
+    "EntitlementRequiredError",
+    "RateLimitError",
+    "NetworkError",
+    "ValidationError",
+    "NotFoundError",
+    "ConflictError",
+    "ServerError",
+    "ERROR_CODES",
+    # Filter language (partners can use this directly to inspect ASTs)
+    "parse_filter",
+    "build_filter_predicate",
+    # Cursor codec (partners building their own pagination shell)
+    "build_cursor_codec",
+    # Version
+    "VERSION",
+    "__version__",
+    # Submodules
+    "errors",
+    "auth",
+    "http_client",
+    "filter_lang",
+    "cursor",
+    "cache",
+]

frootai_orchard-1.0.0/frootai_orchard/_deprecate.py

@@ -0,0 +1,130 @@
+"""A10.3 — Deprecation framework (warn-once-per-process), Python mirror of orchard-types/lib/deprecate.js.
+
+Byte-equivalent behaviour with the npm peer:
+  * WARN ONCE PER PROCESS PER SYMBOL.
+  * NEVER raise — emit to ``sys.stderr`` (never stdout).
+  * Opt-out via ``FROOTAI_SUPPRESS_DEPRECATIONS=1``.
+  * Machine-readable single-line payload:
+    ``[FROOTAI_DEPRECATED] symbol="x" since="1.x.y" removed_in="2.0.0" message="..."``
+
+Doctrine:
+  * Stdlib only — no third-party deps.
+  * Pure ``format_deprecation_line`` exported for tests.
+  * Test injection via keyword args (``emitted``, ``write``, ``env``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from typing import Callable, Mapping, MutableSet, Optional
+
+DEPRECATION_ENV_SUPPRESS = "FROOTAI_SUPPRESS_DEPRECATIONS"
+DEPRECATION_PREFIX = "[FROOTAI_DEPRECATED]"
+_SEMVER_RE = re.compile(r"^\d+\.\d+\.\d+$")
+
+# Per-process suppression set (mirrors the JS module-scope Set).
+_EMITTED_SYMBOLS: MutableSet[str] = set()
+
+
+def format_deprecation_line(
+    *,
+    symbol: str,
+    since: Optional[str] = None,
+    removed_in: Optional[str] = None,
+    message: Optional[str] = None,
+    replacement: Optional[str] = None,
+) -> str:
+    """Pure: build the canonical one-line deprecation message."""
+    if not isinstance(symbol, str) or not symbol:
+        raise TypeError("format_deprecation_line requires non-empty symbol")
+    parts = [
+        DEPRECATION_PREFIX,
+        f"symbol={json.dumps(symbol)}",
+    ]
+    if isinstance(since, str) and _SEMVER_RE.match(since):
+        parts.append(f"since={json.dumps(since)}")
+    if isinstance(removed_in, str) and _SEMVER_RE.match(removed_in):
+        parts.append(f"removed_in={json.dumps(removed_in)}")
+    if isinstance(replacement, str) and replacement:
+        parts.append(f"replacement={json.dumps(replacement)}")
+    if isinstance(message, str) and message:
+        parts.append(f"message={json.dumps(message)}")
+    return " ".join(parts)
+
+
+def emit_deprecation(
+    *,
+    symbol: str,
+    since: Optional[str] = None,
+    removed_in: Optional[str] = None,
+    message: Optional[str] = None,
+    replacement: Optional[str] = None,
+    emitted: Optional[MutableSet[str]] = None,
+    write: Optional[Callable[[str], None]] = None,
+    env: Optional[Mapping[str, str]] = None,
+) -> dict:
+    """Emit a deprecation warning ONCE per process per symbol.
+
+    Returns ``{"emitted": bool, "line": str|None, "reason"?: str}``.
+    """
+    if not isinstance(symbol, str) or not symbol:
+        raise TypeError("emit_deprecation requires non-empty symbol")
+
+    effective_env = env if env is not None else os.environ
+    if effective_env.get(DEPRECATION_ENV_SUPPRESS) == "1":
+        return {"emitted": False, "line": None, "reason": "suppressed_by_env"}
+
+    effective_set = emitted if emitted is not None else _EMITTED_SYMBOLS
+    if symbol in effective_set:
+        return {"emitted": False, "line": None, "reason": "already_emitted_this_process"}
+
+    try:
+        line = format_deprecation_line(
+            symbol=symbol,
+            since=since,
+            removed_in=removed_in,
+            message=message,
+            replacement=replacement,
+        )
+    except Exception as err:  # pragma: no cover - defensive; mirrors npm impl
+        line = (
+            f"{DEPRECATION_PREFIX} symbol={json.dumps(symbol)} "
+            f"message={json.dumps('format_error: ' + str(err))}"
+        )
+
+    def _default_write(s: str) -> None:
+        try:
+            sys.stderr.write(s)
+        except Exception:  # pragma: no cover - never propagate
+            pass
+
+    writer = write if callable(write) else _default_write
+    try:
+        writer(line + "\n")
+    except Exception:  # pragma: no cover - never propagate
+        pass
+    effective_set.add(symbol)
+    return {"emitted": True, "line": line}
+
+
+def _reset_emitted_symbols_for_test() -> None:
+    """TEST UTILITY — clear the per-process set. NEVER call from production."""
+    _EMITTED_SYMBOLS.clear()
+
+
+def _get_emitted_symbols_for_test() -> set:
+    """TEST UTILITY — defensive copy of warned-symbol set."""
+    return set(_EMITTED_SYMBOLS)
+
+
+__all__ = [
+    "DEPRECATION_ENV_SUPPRESS",
+    "DEPRECATION_PREFIX",
+    "format_deprecation_line",
+    "emit_deprecation",
+    "_reset_emitted_symbols_for_test",
+    "_get_emitted_symbols_for_test",
+]

frootai_orchard-1.0.0/frootai_orchard/_orchard_types.py

@@ -0,0 +1,123 @@
+"""
+frootai-orchard — byte-equal enum mirror of @frootai/orchard-types v1.0.0.
+
+This module is **byte-for-byte identical** to:
+    frootai-core/orchard-types/index.js
+
+Drift is prevented by the cross-language enum test in
+scripts/orchard/test/sdk_orchard_py_test.py which loads the JS module via
+subprocess and asserts byte-equality with this module.
+
+Why a separate Python file instead of pip-installing a py-types package:
+    - Zero runtime dependencies (matches @frootai/orchard peer-dep model)
+    - Drift detection runs against the JS source of truth on every regression
+    - Partners get the enums without an extra install
+
+Doctrine:
+    - Every enum is a tuple (immutable at runtime — closest Python equivalent
+      to Object.freeze on an Array).
+    - TIER_RANK is a dict but exposed via MappingProxyType for read-only view.
+    - No exported function has side effects.
+"""
+
+from types import MappingProxyType
+from typing import Mapping, Sequence
+
+# ---------------------------------------------------------------------------
+# Accelerator manifest enums
+# ---------------------------------------------------------------------------
+
+VARIETY_ENUM: Sequence[str] = ("azure", "gcp", "aws", "oss", "hybrid")
+OWNER_TYPE_ENUM: Sequence[str] = ("first_party", "community", "partner", "frootai")
+FROOT_LAYER_ENUM: Sequence[str] = ("F", "R", "O1", "O2", "T")
+RIPENESS_ENUM: Sequence[str] = ("Seedling", "Sapling", "Bearing", "Mature")
+SEASON_ENUM: Sequence[str] = ("Spring", "Summer", "Autumn", "Winter")
+CATEGORY_ENUM: Sequence[str] = (
+    "rag", "agent", "multi-agent", "voice", "vision", "chat", "doc", "code",
+    "infra", "mcp", "security", "search", "data", "eval", "edge",
+    "industry-healthcare", "industry-finance", "industry-retail", "industry-public-sector",
+)
+TRUST_BADGE_ENUM: Sequence[str] = (
+    "microsoft_official", "google_official", "aws_official",
+    "azd_template",
+    "frootai_compatible_full", "frootai_compatible_partial", "frootai_pollinated",
+    "eval_proven", "safety_layer", "production_ready",
+)
+ORIGIN_ENUM: Sequence[str] = ("harvested", "cultivated", "first_party")
+POLLINATION_RELATION_ENUM: Sequence[str] = (
+    "baseline", "extends_to", "alternative", "uses_pattern", "provides_infra",
+)
+POLLINATION_SOURCE_ENUM: Sequence[str] = ("auto", "manual", "community_pr")
+NO_PLAY_MATCH_TAG: str = "no-play-match"
+
+# ---------------------------------------------------------------------------
+# Telemetry enums
+# ---------------------------------------------------------------------------
+
+EVENT_ENUM: Sequence[str] = (
+    "subcommand_invoked",
+    "install_succeeded",
+    "upgrade_to_play_attempted",
+    "tool_invoked",
+)
+
+ALLOWED_PROP_KEYS: Sequence[str] = (
+    "cmd",
+    "variety",
+    "paid",
+    "dry_run",
+    "success",
+    "exit_code",
+    "has_json",
+    "tier_class",
+    "hooks_count",
+    "error_code",
+    "ms_elapsed",
+    "client",
+    "has_args",
+)
+
+# ---------------------------------------------------------------------------
+# Entitlement / tier enums
+# ---------------------------------------------------------------------------
+
+TIER_ENUM: Sequence[str] = ("free", "pro", "team", "business", "enterprise")
+
+TIER_RANK: Mapping[str, int] = MappingProxyType({
+    "free": 0,
+    "pro": 1,
+    "team": 2,
+    "business": 3,
+    "enterprise": 4,
+})
+
+KNOWN_ENTITLEMENTS: Sequence[str] = (
+    "upgrade-to-play",
+    "bushel-sync",
+    "telemetry-dash",
+    "sso-saml",
+    "audit-export",
+)
+
+# ---------------------------------------------------------------------------
+# Pure helpers — no IO, no dependencies
+# ---------------------------------------------------------------------------
+
+
+def is_tier_at_least(tier: str, required: str) -> bool:
+    """Returns True if `tier` is at least `required` per TIER_RANK ordering."""
+    a = TIER_RANK.get(tier)
+    b = TIER_RANK.get(required)
+    if not isinstance(a, int) or not isinstance(b, int):
+        return False
+    return a >= b
+
+
+def is_valid_enum(value: str, enum_seq: Sequence[str]) -> bool:
+    """Returns True if `value` is a valid member of `enum_seq`."""
+    if not isinstance(value, str):
+        return False
+    return value in enum_seq
+
+
+ORCHARD_TYPES_VERSION: int = 1