flashruntime 0.4.1__tar.gz → 0.4.2__tar.gz

{flashruntime-0.4.1/flashruntime.egg-info → flashruntime-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashruntime
-Version: 0.4.1
+Version: 0.4.2
 Summary: Open fault-tolerant distributed ML runtime: strategy planning, job protocol, leases, checkpointing, and recovery across heterogeneous compute.
 Author: Zolli Labs
 License-Expression: Apache-2.0

{flashruntime-0.4.1 → flashruntime-0.4.2}/flashml_workloads/fedavg_driver.py

@@ -29,7 +29,7 @@ from typing import Any, Callable, Protocol, Sequence, TypedDict
 
 from flashml_workloads.fedavg_weights import (
     apply_delta,
-    reduce_deltas,
+    reduce_deltas_with_report,
     require_finite,
 )
 
@@ -73,6 +73,26 @@ class RoundResult(TypedDict):
     mean_loss: float
     job_id: str
 
+    #: The round's contributions whose influence the aggregation capped, as
+    #: ``{"task_id", "norm", "cap", "scale"}`` — empty on an honest round,
+    #: which is every round unless somebody tried.
+    #:
+    #: ``task_id``, not a node id, because a task id is what this driver
+    #: actually holds. `fedavg_weights` reports positional indices; the round
+    #: knows which task each position came from, and a task is what a
+    #: coordinator leases. Resolving that to a MACHINE means deciding which
+    #: attempts count as accepted work, and that judgement already lives in
+    #: exactly one place — the cloud's round recorder, which reads the
+    #: coordinator's task view for provenance and joins on this task id.
+    #: Making a second copy of it here is how the two disagree.
+    #:
+    #: Recorded, never enforced. Nothing is quarantined, no credit withheld,
+    #: no lease refused: with a fleet this small a false positive costs a
+    #: volunteer their machine while a false negative costs one undeserved
+    #: credit, and that asymmetry only points one way. The row exists so the
+    #: owner can look.
+    clipped: list[dict]
+
 
 class RoundPlan(TypedDict):
     """What one round is: the job body to submit, and the task ids it will
@@ -535,7 +555,17 @@ def run_fedavg(
         # download. Anything committing from here on is discarded by
         # construction: we never re-read this job after aggregating.
         collected = _fetch(coord, keys)
-        reduced = reduce_deltas([(d, n) for d, n, _ in collected])
+        reduced, clip_events = reduce_deltas_with_report(
+            [(d, n) for d, n, _ in collected])
+        # `_fetch` preserves `keys`' order one-for-one, and every key in
+        # `keys` came out of the expected-key map, so a clip event's
+        # positional index resolves back to the exact task that sent it.
+        # Positional, NOT a shard number: a round aggregates on a quorum, so
+        # with shard-001 absent the third committer sits at position 2, and
+        # re-deriving `shard-{index:03d}` would name an honest volunteer.
+        by_key = _expected_metrics_keys(job_id, task_ids)
+        clipped = [{"task_id": by_key[keys[e.index]], "norm": e.norm,
+                    "cap": e.cap, "scale": e.scale} for e in clip_events]
         # No weights yet (`initial_weights={}` and nothing aggregated): the
         # round's workers were handed nothing, so what they reported as
         # "the change from what you were given" is the weights themselves.
@@ -561,6 +591,7 @@ def run_fedavg(
             "participants": len(collected),
             "mean_loss": sum(loss * n for _, n, loss in collected) / total_n,
             "job_id": job_id,
+            "clipped": clipped,
         }
         history.append(result)
         if on_round is not None:

{flashruntime-0.4.1 → flashruntime-0.4.2}/flashml_workloads/fedavg_weights.py

@@ -15,18 +15,48 @@ container.
 from __future__ import annotations
 
 import math
+from typing import NamedTuple
 
 __all__ = [
+    "CLIP_FACTOR",
+    "ClipEvent",
     "NonFiniteWeights",
     "WeightShapeMismatch",
     "apply_delta",
     "decode",
     "encode",
     "reduce_deltas",
+    "reduce_deltas_with_report",
     "require_finite",
     "subtract",
 ]
 
+#: How many times the round's MEDIAN contribution norm a single contribution
+#: may be before it is scaled back to that bound.
+#:
+#: 3.0, and the number is load-bearing. The governing property of the cap is
+#: that an honest round is bit-identical to a round with no cap at all:
+#: honest per-shard variation sits well inside 3x the median, so nothing
+#: fires and the arithmetic below is untouched. A factor of 1.0 would clip
+#: roughly half of every honest round and silently alter results that are
+#: correct today — a behaviour change wearing a safety net's clothes.
+CLIP_FACTOR: float = 3.0
+
+
+class ClipEvent(NamedTuple):
+    """One contribution that exceeded the round's cap, and by how much.
+
+    `index` is POSITIONAL into the `contributions` list the caller passed,
+    not a node id: this module is pure stdlib and knows nothing about
+    machines. Attribution is the driver's job — it holds the per-task
+    provenance and maps an index back to whoever sent it.
+    """
+
+    index: int
+    norm: float
+    cap: float
+    scale: float
+
 
 class WeightShapeMismatch(ValueError):
     """Two weight blobs do not describe the same parameter set.
@@ -138,13 +168,102 @@ def apply_delta(base: dict, delta: dict, scale: float = 1.0) -> dict:
     }, "apply_delta")
 
 
-def reduce_deltas(contributions: list[tuple[dict, int]]) -> dict:
+def _l2_norm(blob: dict) -> float:
+    """L2 norm of a delta, flattened across every parameter.
+
+    Only ever called on a blob `require_finite` has already accepted: the
+    multiplication below is a `TypeError` on the `None` a volunteer can put
+    in `data`, and a NaN anywhere would make the norm NaN, `norm > cap`
+    False, and the contribution sail through unscaled.
+    """
+    return math.sqrt(sum(v * v for p in blob.values() for v in p["data"]))
+
+
+def _median(values: list[float]) -> float:
+    """Median, with the even-length case spelled out: the mean of the two
+    middles.
+
+    Which is precisely why the cap is weak at two contributions — the
+    median of two values is their mean, and an attacker moves a mean
+    directly. Robust statistics need a majority to be honest, and with
+    `min_participants = 2` there is no majority to have. Documented, not
+    papered over: this does not fail closed at that quorum and must not be
+    described as protection there.
+    """
+    ordered = sorted(values)
+    mid = len(ordered) // 2
+    if len(ordered) % 2:
+        return ordered[mid]
+    return (ordered[mid - 1] + ordered[mid]) / 2
+
+
+def _scale_blob(blob: dict, scale: float) -> dict:
+    return {name: {"shape": list(p["shape"]),
+                   "data": [scale * v for v in p["data"]]}
+            for name, p in blob.items()}
+
+
+def reduce_deltas(contributions: list[tuple[dict, int]],
+                  *, clip_factor: float = CLIP_FACTOR) -> dict:
     """Sample-weighted mean of per-worker deltas (FedAvg).
 
     Weighting by sample count, not by worker, is what keeps the result
     equal to centralized training on the union of the shards when the
     shards are unequal — which they always are once machines differ.
+
+    A thin wrapper over `reduce_deltas_with_report`, kept because this name
+    has one production caller and 30+ tests pinning it. The clip report is
+    additive; callers that want it ask for it by name.
     """
+    return reduce_deltas_with_report(contributions, clip_factor=clip_factor)[0]
+
+
+def reduce_deltas_with_report(
+    contributions: list[tuple[dict, int]],
+    *,
+    clip_factor: float = CLIP_FACTOR,
+) -> tuple[dict, list[ClipEvent]]:
+    """`reduce_deltas`, plus the list of contributions the cap bound.
+
+    Everything MALFORMED is rejected below — non-positive, non-finite and
+    non-integer sample counts, mismatched shapes, NaN/Inf weights. What none
+    of those guards catch is a contribution that is perfectly well-formed
+    and adversarial: `delta = 1e6`, `n = 500`. Every check passes and the
+    sample-weighted mean moves the model by whatever the sender chose.
+
+    So, after validation and before the mean, each contribution's L2 norm is
+    compared against `C = median(norms) * clip_factor` and anything above it
+    is scaled to `C`. Median-anchored rather than a fixed constant because
+    the right magnitude depends on the model, the learning rate and the
+    round number, none of which this module knows — and because with a
+    majority of honest contributors the median is an honest value, which an
+    attacker-chosen mean is not.
+
+    Bounds MAGNITUDE, not direction. A small, consistently-biased delta
+    every round is unaffected, a node returning zeros still earns credit,
+    and a colluding majority defeats it by construction. It is a cap on how
+    far one contributor can move the model, not result verification.
+
+    Nothing is enforced here beyond the scaling: the events are returned so
+    the caller can record them. Revocation is a human decision.
+    """
+    # First, because it is the function's own configuration rather than
+    # untrusted input, and because the failure mode of getting it wrong is
+    # the worst one available: a non-positive or non-finite factor would
+    # disable the cap silently, the round would still reduce, and it would
+    # still report an empty clip list that an operator reads as "nobody
+    # tried". `clip_factor=0` would additionally zero every contribution.
+    try:
+        usable = math.isfinite(clip_factor) and clip_factor > 0
+    except TypeError:  # not a number at all
+        usable = False
+    if not usable:
+        raise ValueError(
+            f"reduce_deltas: clip_factor must be a finite number > 0, got "
+            f"{clip_factor!r}; a non-positive or non-finite value would "
+            "silently disable the influence cap rather than widening it"
+        )
+
     if not contributions:
         raise ValueError("reduce_deltas: no contributions")
     total = sum(n for _, n in contributions)
@@ -212,12 +331,38 @@ def reduce_deltas(contributions: list[tuple[dict, int]]) -> dict:
         _require_same_params(first, blob)
         require_finite(blob, f"reduce_deltas: contribution {i}")
 
+    # -- bounded influence, and ONLY here: after every guard above, because
+    # a malformed contribution must raise its own error rather than be
+    # quietly scaled into something plausible. Clipping caps a delta's
+    # magnitude and does nothing at all about a negative sample weight.
+    #
+    # `reduced` deliberately reuses the caller's own blob objects for every
+    # contribution that is not clipped, so an honest round accumulates the
+    # exact same float objects in the exact same order as it did before this
+    # existed. Byte-identical is the governing property; rebuilding every
+    # blob "harmlessly" would be the easiest way to lose it.
+    # Computed once, not once per use: deltas are megabytes, and this walks
+    # every weight in every contribution.
+    norms = [_l2_norm(blob) for blob, _ in contributions]
+    cap = _median(norms) * clip_factor
+    clipped: list[tuple[dict, int]] = list(contributions)
+    events: list[ClipEvent] = []
+    for i, ((blob, n), norm) in enumerate(zip(contributions, norms)):
+        # Strict `>` against a cap that is never negative — so a zero-norm
+        # contribution (a converged shard, or a lazy node returning zeros)
+        # is never the one being scaled, and `cap / norm` never divides by
+        # zero. An all-zero round puts the cap at 0.0 too and clips nothing.
+        if norm > cap:
+            scale = cap / norm
+            clipped[i] = (_scale_blob(blob, scale), n)
+            events.append(ClipEvent(index=i, norm=norm, cap=cap, scale=scale))
+
     out: dict = {}
     for name in first:
         acc = [0.0] * len(first[name]["data"])
-        for blob, n in contributions:
+        for blob, n in clipped:
             w = n / total
             for i, v in enumerate(blob[name]["data"]):
                 acc[i] += w * v
         out[name] = {"shape": list(first[name]["shape"]), "data": acc}
-    return out
+    return out, events

{flashruntime-0.4.1 → flashruntime-0.4.2}/flashruntime/protocol/v1alpha1.py

@@ -427,6 +427,60 @@ class TaskAttempt(BaseModel):
     accepted: bool = False
 
 
+class ExecutionEvidence(BaseModel):
+    """What the agent says about the run it is committing. **Evidence, never
+    proof** — the agent is the untrusted party, so every field here is
+    something a liar could fabricate. Its value is that a liar must now keep
+    two stories straight: these numbers have to stay consistent with the
+    elapsed time the *coordinator* measured between claim and commit, which
+    the agent does not control.
+
+    Optional on `CompleteRequest`, and it must stay optional — see the note
+    there.
+
+    NONE MEANS "NOT MEASURED". ZERO MEANS "MEASURED, AND IT WAS ZERO". These
+    are different facts and must never collapse onto one value: 0% GPU on a
+    task that asked for a GPU is the strongest single signal this block
+    carries, and a host with no sampler at all is no signal whatsoever. An
+    agent that cannot read a value sends `None`; a fabricated 0.0 turns "we
+    could not look" into "this node did nothing" and gets an honest
+    volunteer flagged. `image_digest` uses `""` for the same purpose, matching
+    `GpuInfo`'s string fields.
+
+    DELIBERATELY UNCONSTRAINED. No `ge=0`, no upper bound, no format check on
+    the digest. A validator here would let an agent's own self-report 422 the
+    agent's own work — inverting a design in which nothing is ever enforced
+    and everything is at most flagged. An implausible reading is worth more
+    recorded than refused, and refusing it mostly teaches a liar which values
+    pass.
+
+    Fields:
+    - `wall_seconds` — the agent's own clock around the run, excluding input
+      download and output upload. Cross-checked against coordinator-observed
+      elapsed, never trusted alone.
+    - `cpu_percent_mean` / `gpu_util_percent_mean` — mean utilisation over
+      the run, sampled by the agent. HOST-WIDE, not task-scoped: a volunteer
+      machine has other things running on it, so a high reading is weak
+      evidence and a *low* one is the interesting direction.
+    - `image_digest` — which image bytes actually executed, as the host
+      resolved them. `""` for a tier that ran no container at all.
+    - `exit_code` — the process/container exit status. On the reference agent
+      this is 0 whenever it is present at all, because a non-zero exit fails
+      the attempt and never reaches the commit path; it is carried so a
+      runner that commits partial results stays expressible, and so absence
+      still distinguishes an agent that measured from one that did not.
+
+    No `schema_version`: like `GpuInfo` and `CheckpointPart`, this is a
+    nested element of a wire message, not a wire message of its own.
+    """
+
+    wall_seconds: float | None = None
+    cpu_percent_mean: float | None = None
+    gpu_util_percent_mean: float | None = None
+    image_digest: str = ""
+    exit_code: int | None = None
+
+
 # ---------------------------------------------------------------------------
 # Checkpoint manifests (additive, July 2026)
 #

{flashruntime-0.4.1 → flashruntime-0.4.2}/flashruntime/scheduler/__init__.py

@@ -209,6 +209,51 @@ class IsolationAwarePlacement(PlacementPolicy):
     — hardware either exists on a host or it does not, and the submitter's
     isolation posture has nothing to say about it.
 
+    A sixth gate applies to tasks whose payload lists `exclude_nodes`: the
+    claiming node must not be named there. It is the one runtime change
+    upfront redundant assignment cannot be built without — a verification
+    twin carries the same payload as its original and must land on a
+    DIFFERENT machine, and nothing here could previously say "anywhere but
+    there". With a fleet of two, the twin otherwise lands on the same node
+    half the time, verifying nothing at double the cost.
+
+    **Fail closed**, taking the argv/local-data/gpu polarity and not the
+    module gate's, and the asymmetry is the whole argument:
+
+    - A task excluded from everywhere simply never runs, and that announces
+      itself — the queue does not drain and the redundancy slice records
+      `unknown`, which it is required never to render as `pass`.
+    - A twin misplaced onto the excluded node produces a MATCH, which is
+      recorded as agreement, which reads as verified. That failure is
+      invisible after the fact and cannot be distinguished from a real
+      verification by anything downstream. An unplaceable task costs a task;
+      a fake verification costs the reason the feature exists.
+
+    - The requirement must be a genuine *list* of names. A bare string is
+      refused even when it looks right, for the reason `local_inputs` states
+      at length: `"node-a" in "node-alpha"` is True, so a string exclusion
+      would quietly refuse every host whose name contains another's.
+    - Every member must be a `str`. A `None`, an `int`, or a nested object
+      means the exclusion was built wrong — and the node it meant to name is
+      exactly the one a plain membership test would then let through. The
+      whole task fails closed rather than the one member being skipped.
+    - An EMPTY list excludes nobody and runs anywhere, like `gpus: 0` and an
+      empty `local_inputs`. It is what the first member of a pair carries:
+      dispatched before anyone has claimed the other, it has nobody to
+      exclude yet.
+    - The node's own identity must be readable: a non-empty `str` `node_id`.
+      A view that cannot answer "are you the node we must avoid?" is refused,
+      because "we could not tell" resolving to "go ahead" is the same failure
+      the gate exists to prevent, reached from the other side. Scoped to
+      tasks that actually exclude something — an absent or empty exclusion
+      asks no question. It costs nothing real: every node view the claim
+      endpoint builds carries the node_id it just authenticated.
+
+    `allowFallback` does not waive this one either. It waives the sandbox
+    tier and nothing else; a submitter has no standing to say which machine
+    already holds the other half of a verification pair — and the point of
+    the pair is that the node cannot tell it is in one.
+
     Everything genuinely standard keeps the fail-open placement default."""
 
     def eligible(self, task: TaskSpec, node: NodeView) -> bool:
@@ -258,6 +303,25 @@ class IsolationAwarePlacement(PlacementPolicy):
                 )
                 if not isinstance(advertised, list) or len(advertised) < required_gpus:
                     return False  # absent/short/type-confused ⇒ not capable
+        # Fail-closed like the gates above, and checked before the
+        # allowFallback waiver for the same reason: a submitter cannot waive
+        # their way onto the machine already running the other half of their
+        # verification pair — and is not supposed to know there is one.
+        excluded = task.payload.get("exclude_nodes")
+        if excluded is not None:
+            if not isinstance(excluded, list):
+                return False  # type-confused requirement ⇒ fail closed, no crash
+            if excluded:
+                if not all(isinstance(name, str) for name in excluded):
+                    # A non-name member means this list was built wrong, and
+                    # the node it meant to exclude is precisely the one a
+                    # membership test would now let through.
+                    return False
+                node_id = node.get("node_id")
+                if not isinstance(node_id, str) or not node_id:
+                    return False  # cannot answer "is this you?" ⇒ do not risk it
+                if node_id in excluded:
+                    return False
         isolation = task.payload.get("isolation")
         if isolation is None:
             return True  # no isolation payload ⇒ standard, runs anywhere

{flashruntime-0.4.1 → flashruntime-0.4.2}/flashruntime/service/modea.py

@@ -36,6 +36,7 @@ import flashruntime.recipes.command  # noqa: F401 — registers the "command" re
 from flashruntime.leases import LeaseManager
 from flashruntime.protocol.v1alpha1 import (
     ArtifactRecord,
+    ExecutionEvidence,
     JobSpec,
     NodeHeartbeat,
     NodeRegistration,
@@ -350,6 +351,20 @@ class ClaimRequest(BaseModel):
 
 class CompleteRequest(BaseModel):
     output_sha256: str
+    #: What the agent measured about the run it is committing. **Optional,
+    #: and it must stay optional.** Every agent deployed today predates this
+    #: field; making it required would 422 every completion in the fleet the
+    #: moment this coordinator shipped, and the fleet is not reachable to
+    #: upgrade first. Same fail-safe polarity as `NodeRegistration
+    #: .module_capable` and for the same reason — availability, not security:
+    #: an absent block costs a verification signal, a required one costs
+    #: every task.
+    #:
+    #: This coordinator ACCEPTS AND IGNORES it. It keeps no verifications
+    #: ledger, and inventing somewhere to put this would put the runtime in
+    #: the business of judging its own volunteers; the cloud API reads it and
+    #: records a verdict. Absent evidence is `unknown` there — never `pass`.
+    evidence: ExecutionEvidence | None = None
 
 
 class FailRequest(BaseModel):

{flashruntime-0.4.1 → flashruntime-0.4.2/flashruntime.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashruntime
-Version: 0.4.1
+Version: 0.4.2
 Summary: Open fault-tolerant distributed ML runtime: strategy planning, job protocol, leases, checkpointing, and recovery across heterogeneous compute.
 Author: Zolli Labs
 License-Expression: Apache-2.0

{flashruntime-0.4.1 → flashruntime-0.4.2}/flashruntime.egg-info/SOURCES.txt

@@ -118,9 +118,11 @@ tests/test_leases.py
 tests/test_leases_scope.py
 tests/test_leases_sqlite.py
 tests/test_monitor_sampler.py
+tests/test_placement_exclusion.py
 tests/test_placement_gpu.py
 tests/test_placement_local_data.py
 tests/test_planner.py
+tests/test_protocol_evidence.py
 tests/test_protocol_gpu.py
 tests/test_protocol_local_datasets.py
 tests/test_protocol_v1alpha1.py

{flashruntime-0.4.1 → flashruntime-0.4.2}/pyproject.toml

@@ -5,6 +5,19 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flashruntime"
+# 0.4.2 adds ExecutionEvidence and CompleteRequest.evidence — the agent's
+# self-report at commit time. Additive and OPTIONAL on the wire, so the
+# compatibility range does not move and an agent that predates it keeps
+# committing work; the bump is the same rule as 0.4.1's, applied to a
+# wire-visible change even though nothing breaks.
+#
+# flashnode’s floor moves to >=0.4.2,<0.5 in the same change, for the same
+# reason it moved for GpuInfo: `executor/client.py` and `executor/loop.py`
+# import ExecutionEvidence at MODULE scope, so on an older wheel the agent
+# raises ImportError and never registers at all. There is no silent
+# degradation to reason about, which is the one comfort in this shape of
+# floor error.
+#
 # 0.4.1 adds GpuInfo and ResourcesSpec.gpuPerTask. Both are additive wire
 # fields, so the compatibility range does not move — but the PATCH bump is
 # load-bearing, not bookkeeping. The `flashruntime-v0.4.0` tag was cut BEFORE
@@ -21,7 +34,7 @@ name = "flashruntime"
 # must pin a range that includes it. (0.3.0 was the first published release;
 # 0.1.0 and 0.2.0 were declared here but never reached PyPI.) Released from
 # the Zolli-Labs/flashml monorepo by pushing a `flashruntime-vX.Y.Z` tag.
-version = "0.4.1"
+version = "0.4.2"
 description = "Open fault-tolerant distributed ML runtime: strategy planning, job protocol, leases, checkpointing, and recovery across heterogeneous compute."
 readme = "README.md"
 # PEP 639 SPDX expression (string form) — replaces the deprecated

{flashruntime-0.4.1 → flashruntime-0.4.2}/tests/test_fedavg_driver.py

@@ -853,3 +853,81 @@ def test_build_round_returning_duplicate_task_ids_is_refused():
                    initial_weights={"w": {"shape": [1], "data": [0.0]}},
                    build_round=build)
     assert fake.submitted == []
+
+
+# -- bounded influence: who the cap bound, not just that it bound somebody ---
+#
+# `reduce_deltas_with_report` reports POSITIONAL indices into the list it was
+# handed — it is pure stdlib and knows nothing about machines. The driver is
+# the layer that holds per-task provenance, so turning an index back into
+# something an operator can act on is its job, and getting it wrong names the
+# wrong volunteer, which is worse than naming nobody.
+
+
+def test_an_honest_round_reports_nothing_clipped():
+    fake = FakeCoordinator({0: [(0, 1.0, 10), (1, 1.1, 10), (2, 0.9, 10)]})
+    result = run_fedavg(fake, rounds=1, num_shards=3, min_participants=3,
+                        worker_params=_params(),
+                        initial_weights={"w": {"shape": [1], "data": [0.0]}})
+    assert result["history"][0]["clipped"] == []
+
+
+def test_a_round_with_one_adversarial_shard_names_that_shard():
+    """Norms 1.0 / 1.0 / 1e6: the median is 1.0, the cap 3.0, and shard-002
+    enters the average at 3.0 instead of 1000000.0."""
+    fake = FakeCoordinator({0: [(0, 1.0, 10), (1, 1.0, 10), (2, 1e6, 10)]})
+    result = run_fedavg(fake, rounds=1, num_shards=3, min_participants=3,
+                        worker_params=_params(),
+                        initial_weights={"w": {"shape": [1], "data": [0.0]}})
+
+    clipped = result["history"][0]["clipped"]
+    assert len(clipped) == 1
+    assert clipped[0]["task_id"] == "shard-002"
+    assert clipped[0]["norm"] == 1e6
+    assert clipped[0]["cap"] == pytest.approx(3.0)
+    assert clipped[0]["scale"] == pytest.approx(3e-6)
+
+    # And the model actually moved by the bounded amount, not the asked one.
+    assert result["weights"]["w"]["data"][0] == pytest.approx((1.0 + 1.0 + 3.0) / 3)
+
+
+def test_the_clipped_shard_is_identified_positionally_not_by_shard_number():
+    """The test that catches the tempting `f"shard-{index:03d}"`.
+
+    Only shards 0, 2 and 3 of a four-shard round commit — shard-001 is a
+    closed laptop, which is the normal case this driver aggregates on a
+    QUORUM to tolerate. The adversary is shard-003, but it sits at
+    POSITION 2 in the collected list, so an implementation that treats the
+    clip index as a shard number blames shard-002: an honest volunteer.
+    """
+    fake = FakeCoordinator({0: [(0, 1.0, 10), (2, 1.0, 10), (3, 5000.0, 10)]})
+    result = run_fedavg(fake, rounds=1, num_shards=4, min_participants=3,
+                        worker_params=_params(),
+                        initial_weights={"w": {"shape": [1], "data": [0.0]}})
+
+    assert [c["task_id"] for c in result["history"][0]["clipped"]] == ["shard-003"]
+
+
+def test_the_clip_report_reaches_the_on_round_callback():
+    """`on_round` is what the cloud writes a `job_rounds` row from, so an
+    event that only ever appears in the returned history is an event the
+    owner never gets to look at."""
+    seen = []
+    fake = FakeCoordinator({0: [(0, 1.0, 10), (1, 1.0, 10), (2, 1e6, 10)]})
+    run_fedavg(fake, rounds=1, num_shards=3, min_participants=3,
+               worker_params=_params(), on_round=seen.append,
+               initial_weights={"w": {"shape": [1], "data": [0.0]}})
+    assert [c["task_id"] for c in seen[0]["clipped"]] == ["shard-002"]
+
+
+def test_a_command_shaped_round_names_its_own_task_ids():
+    """Task ids come from the round's `RoundPlan`, not from a shard-naming
+    rule: a caller compiling the round as a `command` workload gets
+    `task-000`, `task-001`, ... and the clip report has to follow it."""
+    fake = CommandShapedCoordinator({0: [(0, 1.0, 10), (1, 1.0, 10),
+                                         (2, 1e6, 10)]})
+    result = run_fedavg(fake, rounds=1, num_shards=3, min_participants=3,
+                        worker_params=_params(),
+                        initial_weights={"w": {"shape": [1], "data": [0.0]}},
+                        build_round=_command_plan(3))
+    assert [c["task_id"] for c in result["history"][0]["clipped"]] == ["task-002"]