platformforge 0.1.0__py3-none-any.whl

platformforge/agents/orchestrator.py

@@ -0,0 +1,295 @@
+"""platform-orchestrator machinery — sealed TaskSpec → bounded DAG.
+
+The orchestrator (§12) receives a sealed TaskSpec, inspects it, routes
+specialists through Router V2, assembles the orchestration DAG from
+canonical loop templates (rules/catalog/orchestration.yaml), applies
+the run envelope, and emits a dispatch plan + run record. It is
+deterministic: the model tier on its AgentSpec describes the host's
+reasoning budget, not a code path here.
+
+It never (§13): analyzes domains itself, approves mutations, executes
+arbitrary actions, invents evidence, declares itself done, or verifies
+its own run — `verify` is always a separate stage run by
+platform-verifier.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from platformforge.agents.contracts import (
+    AgentRefusal,
+    AgentRunEnvelope,
+    AgentRunRecord,
+    PlatformTaskSpec,
+    envelope_for,
+    refusal,
+)
+from platformforge.agents.roster import AGENTS, resolve
+from platformforge.agents.taskspec import require_sealed
+from platformforge.models.base import stable_id
+from platformforge.resources import data_path
+
+
+@dataclass
+class DagNode:
+    stage: str
+    agent: str
+    depends_on: tuple[str, ...] = ()
+    conditional: str = ""          # "" | conflicts | accepted
+    external: bool = False         # human-gate — outside the runtime
+    parallel_group: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"stage": self.stage, "agent": self.agent,
+                "depends_on": list(self.depends_on),
+                "conditional": self.conditional,
+                "external": self.external,
+                "parallel_group": self.parallel_group}
+
+
+@dataclass
+class OrchestrationPlan:
+    """The orchestrator's output: a DAG + envelope + run skeleton."""
+    dag: list[DagNode]
+    envelope: AgentRunEnvelope
+    coordinator: str
+    run: AgentRunRecord
+    mode: str = "coordinated"
+    fallbacks: tuple[str, ...] = ()
+    refusal_doc: dict[str, Any] | None = None
+
+    def topological_stages(self) -> list[list[DagNode]]:
+        """Stage groups — same list may run in parallel (§79)."""
+        done: set[str] = set()
+        groups: list[list[DagNode]] = []
+        remaining = {n.stage: n for n in self.dag}
+        while remaining:
+            ready = [n for n in remaining.values()
+                     if all(d in done for d in n.depends_on)]
+            if not ready:
+                break  # cycle guard — surfaced by validate_dag upstream
+            groups.append(sorted(ready, key=lambda n: n.stage))
+            for n in ready:
+                done.add(n.stage)
+                del remaining[n.stage]
+        return groups
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"coordinator": self.coordinator, "mode": self.mode,
+                "dag": [n.to_dict() for n in self.dag],
+                "stages": [[n.stage for n in g]
+                           for g in self.topological_stages()],
+                "envelope": self.envelope.to_dict(),
+                "run": self.run.to_dict(),
+                "fallbacks": list(self.fallbacks),
+                "refusal": self.refusal_doc}
+
+
+def load_loops(path: str | Path | None = None) -> dict[str, Any]:
+    p = Path(path) if path else data_path("rules", "catalog",
+                                          "orchestration.yaml")
+    doc = yaml.safe_load(p.read_text()) or {}
+    return doc.get("loops", {}) or {}
+
+
+def _specialists_for(domains: tuple[str, ...]) -> list[str]:
+    """Routed specialists for the task's domains — must exist."""
+    out = []
+    for d in domains:
+        for a in AGENTS.values():
+            if a.role == "specialist" and d in a.domains:
+                out.append(a.name)
+                break
+    return out
+
+
+def build_dag(loop: dict[str, Any], spec: PlatformTaskSpec,
+              specialists: list[str] | None = None) \
+        -> tuple[list[DagNode], list[str]]:
+    """Instantiate a loop template. `fanout:` stages expand to one node
+    per routed specialist; a later `after: [fanout-id]` waits for ALL of
+    them (§80). Returns (nodes, missing_agent_refs)."""
+    specs = loop.get("stages", [])
+    fanout = specialists if specialists is not None \
+        else _specialists_for(spec.domains)
+    if fanout == []:
+        fanout = ["platform-orchestrator"]
+
+    # pass 1 — instantiate nodes (fanout stages fan out per specialist)
+    instances: list[tuple[str, DagNode]] = []
+    group = 0
+    for st in specs:
+        if st.get("fanout"):
+            group += 1
+            for name in fanout:
+                instances.append((st["id"], DagNode(
+                    stage=f"{st['id']}:{name}", agent=name,
+                    parallel_group=group,
+                    conditional=st.get("if", ""))))
+            continue
+        agent = st.get("agent")
+        external = bool(st.get("external")) or agent == "human-gate"
+        instances.append((st["id"], DagNode(
+            stage=st["id"], agent=agent or "?", external=external,
+            conditional=st.get("if", ""))))
+
+    # pass 2 — resolve `after` template ids to concrete stage names
+    by_tid: dict[str, list[str]] = {}
+    for tid, n in instances:
+        by_tid.setdefault(tid, []).append(n.stage)
+    missing: list[str] = []
+    for st, (tid, n) in zip(
+            [s for s in specs for _ in
+             ([s] if not s.get("fanout") else fanout)],
+            instances):
+        deps = tuple(d for tid_dep in st.get("after", [])
+                     for d in by_tid.get(tid_dep, []))
+        n.depends_on = deps
+        if n.agent != "human-gate" and not n.external \
+                and resolve(n.agent) is None:
+            missing.append(n.agent)
+    return [n for _, n in instances], missing
+
+
+def validate_dag(nodes: list[DagNode]) -> list[str]:
+    """Structural checks — every dep exists, no self-deps, verifier last."""
+    errs = []
+    ids = {n.stage for n in nodes}
+    for n in nodes:
+        for d in n.depends_on:
+            if d not in ids:
+                errs.append(f"{n.stage} depends on missing {d}")
+        if n.stage in n.depends_on:
+            errs.append(f"{n.stage} depends on itself")
+    verifiers = [n for n in nodes
+                 if resolve(n.agent) and resolve(n.agent).role
+                 == "verifier"]
+    for v in verifiers:
+        downstream = [n for n in nodes if v.stage in n.depends_on]
+        if downstream:
+            errs.append("verifier is not terminal — stages "
+                        + ", ".join(n.stage for n in downstream)
+                        + " depend on it")
+    return errs
+
+
+def prepare(spec: PlatformTaskSpec, *, loop_name: str = "platform-audit",
+            router_decision: dict[str, Any] | None = None,
+            specialists: list[str] | None = None,
+            loops: dict[str, Any] | None = None) -> OrchestrationPlan:
+    """§12 — sealed spec in, dispatch plan out. Deterministic.
+
+    Refuses: unsealed complex spec, unknown loop, missing agents,
+    structurally invalid DAG. `loops` overrides the catalog —
+    used by tests and embedders; the CLI always uses the catalog."""
+    complex_ = spec.complexity != "low" or spec.risk in _GOVERN_NONE
+    # polish §24/§28 — a supplied router_decision must be the canonical
+    # platformforge/routing-decision/v1 emitted by routing.decide().
+    # EconomyEngine advice (economy-advice/v1) is refused here — it may
+    # inform the signal, never activate a route.
+    if router_decision:
+        from platformforge.routing.decision import SCHEMA_DEC
+        if router_decision.get("schema") != SCHEMA_DEC:
+            run = _record(spec, dict(router_decision),
+                          verdict="unresolved")
+            return OrchestrationPlan(
+                dag=[], envelope=envelope_for(spec.budget),
+                coordinator="", run=run,
+                refusal_doc=refusal(
+                    AgentRefusal.ROUTE_UNRESOLVED,
+                    "router_decision is not a canonical "
+                    "platformforge/routing-decision/v1 — advice, raw "
+                    "dicts and foreign schemas cannot activate a route",
+                    "produce the decision via "
+                    "platformforge.routing.decision.decide()"))
+    unsealed = require_sealed(spec, complex_=complex_)
+    if unsealed:
+        run = _record(spec, router_decision or {}, verdict="unresolved")
+        return OrchestrationPlan(dag=[], envelope=envelope_for(
+            spec.budget), coordinator="", run=run,
+            refusal_doc=unsealed)
+    loops = load_loops() if loops is None else loops
+    loop = loops.get(loop_name)
+    if loop is None:
+        run = _record(spec, router_decision or {}, verdict="unresolved")
+        return OrchestrationPlan(
+            dag=[], envelope=envelope_for(spec.budget), coordinator="",
+            run=run,
+            refusal_doc=refusal(
+                AgentRefusal.ROUTE_UNRESOLVED,
+                f"no orchestration loop named {loop_name!r}",
+                "pick one of: " + ", ".join(sorted(loops))))
+    nodes, missing = build_dag(loop, spec, specialists=specialists)
+    errs = validate_dag(nodes)
+    env = envelope_for(spec.budget)
+    coordinator = loop.get("coordinator") or ""
+    run = _record(spec, router_decision or {}, verdict="unresolved")
+    if missing or errs:
+        run = _record(spec, router_decision or {}, verdict="unresolved")
+        return OrchestrationPlan(
+            dag=nodes, envelope=env, coordinator=coordinator, run=run,
+            refusal_doc=refusal(
+                AgentRefusal.ROUTE_UNRESOLVED,
+                f"loop {loop_name!r} references missing agents "
+                f"{missing} or has DAG errors {errs}",
+                "fix the loop template or the roster — never skip "
+                "the verifier stage"))
+    run.agents = tuple(sorted({n.agent for n in nodes if not n.external}))
+    run.gates = tuple(n.stage for n in nodes if n.external)
+    # parallel fanout charged against the envelope up front (§113)
+    fanout = max((n.parallel_group for n in nodes), default=0)
+    env.charge(agents=len(run.agents), fanout=max(fanout - 1, 0))
+    over = env.check()
+    if over:
+        return OrchestrationPlan(dag=nodes, envelope=env,
+                                 coordinator=coordinator, run=run,
+                                 refusal_doc=over)
+    return OrchestrationPlan(dag=nodes, envelope=env,
+                             coordinator=coordinator, run=run,
+                             mode="coordinated",
+                             fallbacks=("playbook",))
+
+
+_GOVERN_NONE = ("high", "critical")
+
+
+def _record(spec: PlatformTaskSpec, router: dict[str, Any],
+            verdict: str) -> AgentRunRecord:
+    rid = stable_id("PF-RUN", spec.task_id, spec.spec_hash)
+    return AgentRunRecord(run_id=rid, task_spec_hash=spec.spec_hash,
+                          router_decision=router, verdict=verdict)
+
+
+def checkpoint(record: AgentRunRecord,
+               done_stages: tuple[str, ...]) -> dict[str, Any]:
+    """§140–141 — resumable state preserving spent budget and evidence."""
+    return {"run_id": record.run_id,
+            "task_spec_hash": record.task_spec_hash,
+            "done": list(done_stages),
+            "budget_spent": record.budget,
+            "evidence": list(record.evidence),
+            "verdict": record.verdict}
+
+
+def resume(record: AgentRunRecord, checkpoint: dict[str, Any],
+           spec: PlatformTaskSpec) -> dict[str, Any] | AgentRunRecord:
+    """§142 — resume revalidates before continuing; budget never resets."""
+    if checkpoint.get("task_spec_hash") != spec.spec_hash:
+        return refusal(
+            AgentRefusal.SPEC_UNSEALED,
+            "checkpoint spec hash differs from the current spec — the "
+            "task changed under the run",
+            "discard the checkpoint and start a new run")
+    if checkpoint.get("run_id") != record.run_id:
+        return refusal(
+            AgentRefusal.ROUTE_UNRESOLVED,
+            "checkpoint run_id does not match the record",
+            "resume with the checkpoint emitted by the same run")
+    record.checkpoint = dict(checkpoint)
+    record.verdict = "candidate"  # resumed work is unverified until close
+    return record

platformforge/agents/planner.py

@@ -0,0 +1,116 @@
+"""platform-planner — turn a user goal into a TaskSpec (§14).
+
+Deterministic intake: domain inference is a declared keyword table, not
+a model call. The planner emits a *draft* spec — it never executes,
+never approves, never verifies (§15).
+"""
+
+from __future__ import annotations
+
+from platformforge.agents.contracts import PlatformTaskSpec
+from platformforge.agents.taskspec import MUTATING_CAPS
+from platformforge.models.base import stable_id
+
+# intent keyword → domain. Declared data: an operator can audit why a
+# domain was inferred; nothing is hidden in a prompt.
+_DOMAIN_KEYWORDS: dict[str, tuple[str, ...]] = {
+    "iac": ("terraform", "hcl", "tofu", "plan", "state", "iac",
+            "module"),
+    "k8s": ("kubernetes", "k8s", "manifest", "helm", "kustomize",
+            "deployment", "pod", "cluster", "workload"),
+    "gitops": ("argocd", "flux", "gitops", "rollout"),
+    "aws": ("aws", "iam", "s3", "ec2", "vpc", "eks", "rds"),
+    "crossplane": ("crossplane", "xrd", "composition", "claim"),
+    "sre": ("slo", "sli", "incident", "latency", "burn", "otel",
+            "reliability", "capacity", "outage"),
+    "security": ("security", "secret", "sbom", "supply", "cve",
+                 "signature", "slsa", "exposure", "vulnerability"),
+    "finops": ("cost", "finops", "billing", "spend", "savings",
+               "rightsizing", "focus"),
+    "graph": ("dependency", "blast", "impact", "graph", "path"),
+    "fleet": ("fleet", "clusters", "accounts", "org", "portfolio"),
+    "policy": ("policy", "opa", "kyverno", "cel", "governance",
+               "compliance"),
+    "product": ("golden", "self-service", "dx", "adoption",
+                "developer", "maturity"),
+    "ai": ("gpu", "mig", "model serving", "ai platform", "llm infra"),
+    "federation": ("federation", "forgenode", "sibling forge",
+                   "export policy"),
+}
+
+_SCOPE_KEYWORDS = {
+    "fleet": ("fleet", "organization", "org-wide", "all clusters",
+              "all accounts"),
+    "runtime": ("incident", "running", "live", "production", "slo"),
+    "change": ("change", "migrate", "upgrade", "deploy", "apply",
+               "rollout"),
+}
+
+_EVIDENCE_BY_DOMAIN = {
+    "iac": ("iac artifacts", "plan facts", "state facts"),
+    "k8s": ("manifest facts", "coverage"),
+    "aws": ("cloud inventory facts", "coverage"),
+    "sre": ("telemetry facts", "freshness"),
+    "security": ("security facts", "sbom/material"),
+    "finops": ("cost facts", "denominators"),
+    "fleet": ("member observations", "coverage"),
+    "graph": ("graph with provenance",),
+}
+
+
+def infer_domains(intent: str) -> tuple[str, ...]:
+    terms = intent.lower()
+    out = [d for d, kws in _DOMAIN_KEYWORDS.items()
+           if any(k in terms for k in kws)]
+    return tuple(sorted(out))
+
+
+def infer_scope(intent: str) -> str:
+    terms = intent.lower()
+    for scope, kws in _SCOPE_KEYWORDS.items():
+        if any(k in terms for k in kws):
+            return scope
+    return "repo"
+
+
+def infer_complexity(intent: str, domains: tuple[str, ...],
+                     scope: str) -> str:
+    terms = intent.lower()
+    if scope == "fleet" or len(domains) >= 3 or \
+            any(w in terms for w in ("entire", "whole", "audit",
+                                     "across")):
+        return "high"
+    if len(domains) == 2 or scope in ("runtime", "change"):
+        return "medium"
+    return "low"
+
+
+def plan(intent: str, *, domains: tuple[str, ...] | None = None,
+         risk: str = "low", complexity: str | None = None,
+         autonomy: str = "read-only",
+         acceptance_criteria: tuple[str, ...] | None = None,
+         rollback_requirement: str = "none") -> PlatformTaskSpec:
+    """intent → draft PlatformTaskSpec. Caller reviews + seals it."""
+    doms = domains or infer_domains(intent)
+    scope = infer_scope(intent)
+    cx = complexity or infer_complexity(intent, doms, scope)
+    if risk == "low" and scope == "change":
+        risk = "high"
+    ev = sorted({e for d in doms
+                 for e in _EVIDENCE_BY_DOMAIN.get(d, ("facts",))}
+                | {"coverage", "freshness"})
+    budget = {"low": "small", "medium": "standard",
+              "high": "deep"}.get(cx, "standard")
+    if risk in ("high", "critical"):
+        budget = "critical" if risk == "critical" else "deep"
+    spec = PlatformTaskSpec(
+        task_id=stable_id("PF-TASK", intent, ",".join(doms), scope),
+        intent=intent, scope=scope, domains=doms, risk=risk,
+        complexity=cx, evidence_requirements=tuple(ev),
+        acceptance_criteria=acceptance_criteria
+        or (("every domain answer carries fact_ids or a named "
+             "unresolved"), "independent verifier closes the run"),
+        autonomy=autonomy,
+        forbidden_capabilities=MUTATING_CAPS,
+        rollback_requirement=rollback_requirement, budget=budget)
+    return spec

platformforge/agents/playbook.py

@@ -0,0 +1,51 @@
+"""Playbook — coordinator decomposition as sequential steps.
+
+This is the zero-subagent floor (§166–170): a host without native agent
+delegation runs the same plan as explicit phases, with identical
+evidence requirements. Nothing about the run becomes unverifiable when
+fan-out is unavailable — the orchestrator's DAG degrades to a list.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.agents.contracts import AgentRefusal, refusal
+from platformforge.agents.roster import AGENTS, coordinator_for, resolve
+
+
+def playbook(coordinator: str = "platform-orchestrator",
+             domain: str | None = None) -> dict[str, Any]:
+    if domain and coordinator == "platform-orchestrator":
+        spec = coordinator_for(domain) or AGENTS[coordinator]
+    else:
+        spec = resolve(coordinator)
+        if spec is None:
+            return refusal(
+                AgentRefusal.UNKNOWN_AGENT,
+                f"{coordinator!r} is not in the canonical roster",
+                "agents list — pick a name that exists")
+    steps = [
+        {"step": 1, "verb": "inspect", "why": "inventory artifacts"},
+        {"step": 2, "verb": f"analyze ({', '.join(spec.domains)})",
+         "why": "facts over the domain artifacts"},
+        {"step": 3, "verb": "judge", "why": "rules over facts → findings"},
+        {"step": 4, "verb": "graph build + gaps",
+         "why": "wire provenance, surface structural gaps"},
+        {"step": 5, "verb": "economy",
+         "why": "report context spend — never claim unmeasured savings"},
+    ]
+    if spec.role in ("coordinator", "orchestrator"):
+        steps.insert(1, {"step": 1.5, "verb": "route",
+                         "why": "pick specialists via routing signals"})
+        steps[0]["step"] = 1
+    return {"agent": spec.name, "role": spec.role,
+            "mode": "playbook",
+            "steps": steps, "delegates_to": list(spec.delegates_to),
+            "access": spec.access,
+            "contract": {"when": spec.when_to_enter,
+                         "when_not_to_enter": spec.when_not_to_enter,
+                         "never": spec.never,
+                         "required_evidence": list(spec.required_evidence),
+                         "verifier": spec.verifier,
+                         "outputs": list(spec.outputs)}}

platformforge/agents/referee.py

@@ -0,0 +1,132 @@
+"""platform-debate-referee — deterministic adjudication (cycle5.1 §24–26).
+
+Positions are scored on ten declared axes, never averaged into mush:
+
+    tier                 evidence tier (lower wins)
+    freshness            source/claim freshness (current|fresh|stale|...)
+    version_compat       does the claim's version basis match context
+    scope                does the claim cover the asked scope
+    contradictory        count of unresolved contradictions against it
+    completeness         fraction of required evidence fields present
+    coverage             fraction of asked scope the evidence covers
+    runtime_alignment    claim consistent with runtime evidence
+    risk                 accepting a risky claim needs stronger evidence
+    historical_support   claim supported by history patterns
+
+A position with no evidence loses regardless of prose confidence. Ties
+and gaps are explicit in the receipt; the referee never averages
+positions into a compromise (§26).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.models.base import stable_id
+
+_FRESH = {"current": 0, "fresh": 1, "stale": 3,
+          "deprecated": 5, "superseded": 5, "conflicted": 4,
+          "unresolved": 6}
+
+# weight per axis — evidence still dominates, but the §25 axes all move
+# the score (§115 + cycle5.1 expansion: coverage, runtime alignment,
+# risk, historical support)
+_W = {"tier": 10.0, "freshness": 3.0, "version_compat": 4.0,
+      "scope": 3.0, "contradictory": 8.0, "completeness": 4.0,
+      "coverage": 4.0, "runtime_alignment": 4.0, "risk": 6.0,
+      "historical_support": 2.0}
+
+_REQUIRED_EVIDENCE_FIELDS = ("fact_id", "kind", "tier")
+
+_RISK = {"low": 0.0, "medium": 1.0, "high": 2.0, "critical": 3.0}
+
+
+def _tri(value: Any) -> float:
+    """tri-state: True→1.0, False→0.0, unknown/absent→0.5."""
+    return 1.0 if value is True else 0.0 if value is False else 0.5
+
+
+def _completeness(p: dict[str, Any]) -> float:
+    """Fraction of positions' evidence refs that resolve to full facts."""
+    ev = p.get("evidence_facts") or []
+    if not ev:
+        return 0.0
+    full = sum(1 for e in ev
+               if isinstance(e, dict)
+               and all(e.get(k) is not None
+                       for k in _REQUIRED_EVIDENCE_FIELDS))
+    return full / len(ev)
+
+
+def _score(p: dict[str, Any]) -> dict[str, Any]:
+    tier = p.get("evidence_tier", 7)
+    try:
+        tier = min(max(int(tier), 0), 7)
+    except (TypeError, ValueError):
+        tier = 7
+    freshness = _FRESH.get(str(p.get("freshness", "unresolved")).lower(), 6)
+    vc = _tri(p.get("version_compat"))
+    scope = _tri(p.get("scope_match"))
+    contradictions = len(p.get("contradictions") or [])
+    completeness = _completeness(p)
+    coverage = p.get("coverage")
+    try:
+        coverage = min(max(float(coverage), 0.0), 1.0)
+    except (TypeError, ValueError):
+        coverage = 0.0
+    runtime = _tri(p.get("runtime_alignment"))
+    risk = _RISK.get(str(p.get("risk", "low")).lower(), 0.0)
+    history = _tri(p.get("historical_support"))
+
+    ev = p.get("evidence_fact_ids") or p.get("evidence") or []
+    has_ev = bool(ev) or completeness > 0
+    score = (100.0 if has_ev else 0.0)
+    score -= _W["tier"] * tier
+    score -= _W["freshness"] * freshness
+    score += _W["version_compat"] * vc
+    score += _W["scope"] * scope
+    score -= _W["contradictory"] * min(contradictions, 3)
+    score += _W["completeness"] * completeness
+    score += _W["coverage"] * coverage
+    score += _W["runtime_alignment"] * runtime
+    # risk penalizes a weak-evidence position, not a cautious one
+    score -= _W["risk"] * risk * (1.0 if tier >= 4 else 0.25)
+    score += _W["historical_support"] * history
+    return {"agent": p.get("agent", "?"), "claim": p.get("claim", ""),
+            "tier": tier, "freshness": freshness,
+            "version_compat": vc, "scope": scope,
+            "contradictions": contradictions,
+            "completeness": round(completeness, 3),
+            "coverage": round(coverage, 3),
+            "runtime_alignment": runtime,
+            "risk": p.get("risk", "low"),
+            "historical_support": history,
+            "evidence_count": len(ev), "score": round(score, 3),
+            "evidence": ev}
+
+
+def referee(positions: list[dict[str, Any]]) -> dict[str, Any]:
+    """positions: [{agent, claim, evidence_fact_ids|evidence_facts,
+    evidence_tier, freshness, version_compat, scope_match, coverage,
+    runtime_alignment, risk, historical_support, contradictions, ...}]
+    → winner + receipt. Ties/gaps explicit."""
+    scored = [_score(p) for p in positions]
+    scored.sort(key=lambda s: -s["score"])
+    winner = scored[0] if scored else None
+    tied = [s for s in scored if winner and s["score"] == winner["score"]]
+    winner_has_ev = bool(winner and (winner["evidence"]
+                                     or winner["completeness"] > 0))
+    return {
+        "winner": winner,
+        "tied": len(tied) > 1,
+        "positions": scored,
+        "unresolved": winner is None or not winner_has_ev,
+        "receipt": {"refusal_code": None if winner_has_ev
+                    else "platform.evidence.unresolved",
+                    "receipt_id": stable_id(
+                        "PF-REF", str(len(positions)),
+                        ",".join(sorted(p.get("agent", "?")
+                                        for p in positions)))},
+        "axes": sorted(_W),
+        "note": "ten declared axes decide; no position is averaged away",
+    }