feat(harness): P3 — uniform ctx hook convention (rcust)

harness.meta.HookCtx (frozen): .domain, .base_url, .meta (RecipeMeta), .deps
(provisioned dep creds from $CCCI_DEPS_FILE or None), .op (current lifecycle op
or None); built via meta.hook_ctx() at each hook call site.

All recipe callables now take ctx: EXTRA_ENV(ctx), UPGRADE_EXTRA_ENV(ctx),
READY_PROBE(ctx), BACKUP_VERIFY(ctx), SCREENSHOT(page, ctx), ops.py pre_<op>(ctx).
Dict-valued EXTRA_ENV/UPGRADE_EXTRA_ENV unchanged (only the callable signature
moved). Call sites converted: deploy_app env shaping, perform_upgrade,
wait_ready_probes (gains op=), _perform_op BACKUP_VERIFY, screenshot.capture,
_run_pre_hook.

Legacy signatures fail FAST with a clear migration message: the registry carries
hook_params per hook key, enforced at meta.load() (MetaError names the old vs new
signature); ops.py pre-op hooks get the same check at the orchestrator call site
(meta.check_hook_signature) — no silent TypeError mid-run.

Migrated every in-repo user mechanically (17 ops.py files; cryptpad/lasuite-*/
mailu EXTRA_ENV; mumble+lasuite-drive READY_PROBE; ghost/discourse BACKUP_VERIFY)
— seeded values, probes and assertions byte-identical (domain -> ctx.domain;
keycloak pre_restore's meta arg -> ctx.meta).

Unit tests: hook_ctx field contract, ctx.deps from the run deps file, legacy-
signature MetaError (READY_PROBE/EXTRA_ENV/SCREENSHOT + pre-op checker), ctx
signatures accepted. Docs table regenerated (signature docs in key docs).

Verified on cc-ci: cc-ci-run -m pytest tests/unit -q -> 180 passed; scripts/lint.sh -> PASS.

runner/harness/meta.py

@@ -23,6 +23,8 @@ from __future__ import annotations
 import copy
 import dataclasses
 import difflib
+import inspect
+import json
 import os
 from collections.abc import Callable
 
@@ -48,6 +50,10 @@ class Key:
     doc: str
     validate: Callable[[object], None] | None = None
     deprecated: bool = False
+    # Expected positional-parameter names for a callable value (rcust P3 uniform ctx convention).
+    # Enforced at load so a legacy-signature hook (e.g. `def READY_PROBE(domain)`) fails with a
+    # CLEAR MetaError naming the migration — never a silent TypeError mid-run.
+    hook_params: tuple[str, ...] | None = None
 
 
 KEYS: tuple[Key, ...] = (
@@ -76,7 +82,8 @@ KEYS: tuple[Key, ...] = (
         "READY_PROBE",
         "hook",
         None,
-        "Callable returning extra readiness probes, run after install AND after upgrade: HTTP `{host, path, ok}` or TCP `{tcp_host, tcp_port, stable}`.",
+        "Callable `(ctx) -> [probe, ...]` returning extra readiness probes, run after install AND after upgrade: HTTP `{host, path, ok}` or TCP `{tcp_host, tcp_port, stable}`.",
+        hook_params=("ctx",),
     ),
     Key(
         "UPGRADE_BASE_VERSION",
@@ -88,19 +95,22 @@ KEYS: tuple[Key, ...] = (
         "BACKUP_VERIFY",
         "hook",
         None,
-        "Callable `-> bool` post-backup data-capture check; `False` re-runs the backup (truncated-dump race guard), retried up to 3 attempts.",
+        "Callable `(ctx) -> bool` post-backup data-capture check; `False` re-runs the backup (truncated-dump race guard), retried up to 3 attempts.",
+        hook_params=("ctx",),
     ),
     Key(
         "UPGRADE_EXTRA_ENV",
         "dict_or_hook",
         None,
-        "Extra `.env` keys applied after the PR-head checkout, before the chaos redeploy (env that exists only at head).",
+        "Extra `.env` keys applied after the PR-head checkout, before the chaos redeploy (env that exists only at head). Dict, or callable `(ctx) -> dict`.",
+        hook_params=("ctx",),
     ),
     Key(
         "EXTRA_ENV",
         "dict_or_hook",
         {},
-        "Extra `.env` keys applied at EVERY deploy (base install AND upgrade old-app). Callable form derives values from the per-run domain.",
+        "Extra `.env` keys applied at EVERY deploy (base install AND upgrade old-app). Dict, or callable `(ctx) -> dict` deriving values from the per-run domain (`ctx.domain`).",
+        hook_params=("ctx",),
     ),
     Key(
         "DEPS",
@@ -118,7 +128,8 @@ KEYS: tuple[Key, ...] = (
         "SCREENSHOT",
         "hook",
         None,
-        "Callable driving Playwright to a safe, credential-free post-login view for the results-card screenshot (default: landing page).",
+        "Callable `(page, ctx)` driving Playwright to a safe, credential-free post-login view for the results-card screenshot (default: landing page).",
+        hook_params=("page", "ctx"),
     ),
     # (CHAOS_BASE_DEPLOY, OIDC_AT_INSTALL and SKIP_GENERIC were deleted in restructure P2:
     # compose.ccci.yml is first-class + auto-chaos; install-time deps wiring is the only mode;
@@ -145,6 +156,28 @@ def meta_path(recipe: str, tests_dir: str | None = None) -> str:
     return os.path.join(tests_dir or TESTS_DIR, recipe, "recipe_meta.py")
 
 
+def check_hook_signature(fn, expected: tuple[str, ...], where: str) -> None:
+    """Enforce the uniform ctx hook convention (rcust P3): a hook callable's positional parameters
+    must be exactly `expected` (e.g. ("ctx",) or ("page", "ctx")). A legacy-signature hook (the
+    pre-restructure `(domain)` / `(domain, meta)` / `(page, domain, meta)` forms) raises a CLEAR
+    MetaError naming the migration — never a silent TypeError mid-run."""
+    try:
+        params = [
+            p.name
+            for p in inspect.signature(fn).parameters.values()
+            if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
+        ]
+    except (TypeError, ValueError):  # builtins/odd callables — let the call site surface it
+        return
+    if tuple(params) != expected:
+        raise MetaError(
+            f"{where}: hook signature is ({', '.join(params)}) — the recipe-customization "
+            f"restructure (P3) changed ALL recipe hook signatures to ({', '.join(expected)}); "
+            f"read fields off the HookCtx (ctx.domain, ctx.base_url, ctx.meta, ctx.deps, ctx.op). "
+            f"See docs/recipe-customization.md §5."
+        )
+
+
 def _coerce(key: Key, value: object, path: str) -> object:
     """Validate `value` against `key`'s declared type; normalize containers (tuple[int]/list[str]).
     Raises MetaError on mismatch — including a callable supplied for a data-typed key."""
@@ -209,6 +242,8 @@ def load(recipe: str, tests_dir: str | None = None):
                     f"underscore-prefixed (e.g. _{name})."
                 )
             values[name] = _coerce(key, ns[name], path)
+            if key.hook_params and callable(values[name]):
+                check_hook_signature(values[name], key.hook_params, f"{path}: {name}")
             if key.validate:
                 key.validate(values[name])
     return RecipeMeta(**values)
@@ -231,17 +266,55 @@ def non_default(meta) -> dict:
     return out
 
 
-def _env_map(value, domain: str) -> dict[str, str]:
+@dataclasses.dataclass(frozen=True)
+class HookCtx:
+    """The single argument every recipe hook receives (rcust P3 uniform ctx convention):
+    `EXTRA_ENV(ctx)`, `UPGRADE_EXTRA_ENV(ctx)`, `READY_PROBE(ctx)`, `BACKUP_VERIFY(ctx)`,
+    `SCREENSHOT(page, ctx)`, ops.py `pre_<op>(ctx)`."""
+
+    domain: str  # the app's per-run domain
+    base_url: str  # https://<domain>
+    meta: object  # the recipe's full RecipeMeta
+    deps: dict | None  # provisioned dep creds ({dep_recipe: entry}) or None if absent/empty
+    op: str | None  # current lifecycle op (install|upgrade|backup|restore) or None
+
+
+def _run_deps() -> dict | None:
+    """The current run's provisioned dep creds from $CCCI_DEPS_FILE (either shape), or None.
+    Read directly (not via harness.deps) to keep meta.py import-cycle-free."""
+    path = os.environ.get("CCCI_DEPS_FILE")
+    if not path or not os.path.exists(path):
+        return None
+    try:
+        with open(path) as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return None
+    if isinstance(data, dict):
+        return data or None
+    if isinstance(data, list):
+        out = {e["recipe"]: e for e in data if isinstance(e, dict) and e.get("recipe")}
+        return out or None
+    return None
+
+
+def hook_ctx(domain: str, meta, *, op: str | None = None) -> HookCtx:
+    """Build the HookCtx for a hook call site. Dep creds are picked up from the run's
+    $CCCI_DEPS_FILE when present (None otherwise)."""
+    return HookCtx(domain=domain, base_url=f"https://{domain}", meta=meta, deps=_run_deps(), op=op)
+
+
+def _env_map(value, ctx: HookCtx) -> dict[str, str]:
     if callable(value):
-        value = value(domain)
+        value = value(ctx)
     return {str(k): str(v) for k, v in (value or {}).items()}
 
 
-def extra_env(meta, domain: str) -> dict[str, str]:
-    """Resolve EXTRA_ENV (dict or callable(domain)->dict) to the concrete per-run env map."""
-    return _env_map(meta.EXTRA_ENV, domain)
+def extra_env(meta, ctx: HookCtx) -> dict[str, str]:
+    """Resolve EXTRA_ENV (dict or callable(ctx)->dict) to the concrete per-run env map."""
+    return _env_map(meta.EXTRA_ENV, ctx)
 
 
-def upgrade_extra_env(meta, domain: str) -> dict[str, str]:
-    """Resolve UPGRADE_EXTRA_ENV (dict or callable(domain)->dict) to the concrete env map."""
-    return _env_map(meta.UPGRADE_EXTRA_ENV, domain)
+def upgrade_extra_env(meta, ctx: HookCtx) -> dict[str, str]:
+    """Resolve UPGRADE_EXTRA_ENV (dict or callable(ctx)->dict) to the concrete env map."""
+    return _env_map(meta.UPGRADE_EXTRA_ENV, ctx)