# Probity Mesh-Quiescence,v2

**predicateType:** `https://getprobity.dev/predicate/v2/mesh-quiescence`

A mesh-quiescence attestation is a signed, offline-verifiable statement about the **freeze-atomicity**
of an isolation substrate: that a set of co-resident microVMs was brought to a hypervisor-enforced
quiescent state (every guest CPU paused) with bounded, measured timing, and that no in-flight
inter-VM segment escaped that freeze without being captured. Where a
[security-verdict](../v1/security-verdict.md) reports what an attack corpus did to a single artifact, a
mesh-quiescence attestation reports the *substrate-level* property that makes a clean freeze
trustworthy: the window between cutting the inter-agent proxy and pausing the recipient VM is closed,
bounded, and witnessed.

This is the substrate evidence the [a2a-mesh-scorecard](a2a-mesh-scorecard.md) leans on for its
freeze-tier `quiescence_sound` flag. It is also the first wave-1 predicate whose property a
perimeter-only sandbox **cannot** emit: the freeze is enforced at the hypervisor memory boundary
(a `KVM` vCPU pause), not at a syscall or network shim, and the captured-segment evidence is read
from the host's own view of the guest socket buffers. A tool that intercepts at the application or
network perimeter has no quiescent-CPU primitive and no host-side socket-buffer capture to attest.

This document specifies the predicate body. The signing envelope, subject binding, and offline-verify
mechanics are in [signing-envelope.md](../v1/signing-envelope.md).

The key words MUST, MUST NOT, REQUIRED, SHOULD, MAY, and OPTIONAL are to be interpreted as in
[RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).

## Subject

The subject is the **frozen-VM substrate, by MeshManifest digest** - a single digest that commits to
the ordered set of per-VM byte-identity substrate-integrity roots the freeze ran over. It is NOT a
post-execution snapshot digest; it is the boot-time substrate identity of the mesh that was frozen.

```json
"subject": [
  { "name": "<mesh-topology-label>", "digest": { "sha256": "<64-hex-mesh-manifest-digest>" } }
]
```

The MeshManifest digest is `SHA-256` of the canonical JSON array of the N per-VM byteident
substrate-integrity digests, captured **at boot, not from the post-exec snapshot**. A producer MUST
NOT synthesize a missing per-VM digest; every VM in the frozen mesh carries a real substrate-integrity
digest or the attestation is refused. This binding lets a verifier link the timing-and-atomicity
evidence to the exact substrate it was measured on.

## Predicate

```json
{
  "topology": {
    "vm_count": 2,
    "netns_per_vm": true,
    "veth_p2p_31": true,
    "denied_cidrs": ["10.0.0.0/8"],
    "cap_net_raw_dropped": true,
    "ipv6_posture": "disabled"
  },
  "deltas": {
    "fc_pause_ns":  { "p50": 960920, "p90": 1327174, "p99": 1327174, "max": 1327174, "n": 6 },
    "max_skew_ns":  { "p50": 56526,  "p90": 61419,   "p99": 61419,   "max": 61419,   "n": 3 },
    "proxy_stop_ns":{ "p50": 1224276,"p90": 1482445, "p99": 1482445, "max": 1482445, "n": 3 },
    "tx_escape": {
      "window_ns": 0,
      "escaped_segments": 0,
      "recipient_state_at_escape": "Paused"
    }
  },
  "mattern_ledger_sha256": "<64-hex>",
  "tcp_repair_queue_digests": [],
  "egress_policy_digest": "<64-hex>",
  "environment_attestations": [
    { "type": "host-kernel", "claim": "honest-assumed" }
  ],
  "runs": 3,
  "corpus_sha256": "<64-hex>",
  "engine_commit": "<engine-commit>",
  "fc_version": "1.16.0"
}
```

## Field semantics

- **`topology`** (REQUIRED) - the network-containment facts of the frozen mesh. Each field is a fact a
  verifier reads but cannot itself re-derive from the predicate (they are host self-assertions carried
  under the signature; see the honesty section):
  - **`vm_count`** (REQUIRED, integer) - the number of microVMs in the mesh.
  - **`netns_per_vm`** (REQUIRED, boolean) - `true` iff each VM sits in its own network namespace.
  - **`veth_p2p_31`** (REQUIRED, boolean) - `true` iff each VM is wired with a point-to-point `/31`
    veth pair (no shared L2 segment).
  - **`denied_cidrs`** (REQUIRED, array of strings) - the CIDR ranges denied by the closed-world
    egress policy.
  - **`cap_net_raw_dropped`** (REQUIRED, boolean) - `true` iff `CAP_NET_RAW` was dropped (no raw
    sockets, so no source-address spoofing from inside a guest).
  - **`ipv6_posture`** (REQUIRED, string) - the declared IPv6 posture (for example `disabled`, or a
    tier-specific label). An undeclared posture is non-conforming; the field MUST be a non-empty
    string.

- **`deltas`** (REQUIRED) - the measured freeze-atomicity timing distributions and the in-flight
  escape record. The three distributions each carry the **fixed key set** `{p50, p90, p99, max, n}`
  (nanoseconds for the timing keys; `n` is the sample count); a producer MUST emit all five keys for
  each distribution.
  - **`fc_pause_ns`** (REQUIRED, distribution) - the per-VM hypervisor pause latency
    (`KVM` vCPU pause) distribution. This is the freeze primitive's own cost.
  - **`max_skew_ns`** (REQUIRED, distribution) - the worst inter-VM pause skew: the spread between the
    first and last VM reaching the paused state in a single freeze. A bounded skew is what makes the
    freeze *atomic* across the mesh rather than a staggered shutdown.
  - **`proxy_stop_ns`** (REQUIRED, distribution) - the latency to stop the inter-agent proxy (the sole
    inter-VM channel) at the cut point.
  - **`tx_escape`** (REQUIRED, object) - the atomicity-window escape record. The window is the gap
    between cutting the proxy and pausing the recipient VM. Fields:
    - **`window_ns`** (REQUIRED, integer) - the measured width of that window in nanoseconds.
    - **`escaped_segments`** (REQUIRED, integer >= 0) - the count of inter-VM TCP segments that
      crossed in the window. Every escaped segment MUST be captured host-side (see
      `tcp_repair_queue_digests`); the invariant is "captured", not "zero" - though zero is the
      common clean case.
    - **`recipient_state_at_escape`** (REQUIRED, string) - the recipient VM's state at the moment of
      escape. For the atomicity invariant to hold this MUST be `Paused`: a segment delivered to a live
      recipient would be a real escape, not a captured-and-contained one.

- **`mattern_ledger_sha256`** (REQUIRED) - the SHA-256 of the proxy's open/close ledger, the Mattern
  net-zero credit witness. A clean freeze requires the inter-agent channel to reach a net-zero credit
  state (every opened stream closed) before the pause; this digest pins that ledger so a verifier can
  resolve and re-hash it.

- **`tcp_repair_queue_digests`** (REQUIRED, array of strings) - the host-side socket-buffer captures
  taken at the cut point (`T_cut`), one digest per captured queue. These are the evidence that any
  escaped segment was captured rather than delivered. An empty array is conforming and is the expected
  shape when `escaped_segments == 0`.

- **`egress_policy_digest`** (REQUIRED) - the SHA-256 of the closed-world default-deny external-egress
  policy in force for the run. This is the precondition that makes the captured segment non-launderable:
  the only path a captured segment could leave by is external egress, and that path is default-deny.
  The digest pins the policy so a verifier can compare it against an auditor-approved policy.

- **`environment_attestations`** (REQUIRED, array) - the host-trust attestations for the run. Each
  entry is an object with at least a `type` and a `claim`. For the honest-host tier the array carries
  `[{"type": "host-kernel", "claim": "honest-assumed"}]`. A hardware attestation (a SEV-SNP / TDX
  quote) or a zkVM receipt drops into the same slot as an additional entry with no schema break - the
  array is intentionally extensible so a stronger host-trust root can be added additively within v2.

- **`runs`** (REQUIRED, integer) - the number of measured freeze runs the distributions summarize.

- **`corpus_sha256`** (REQUIRED) - the SHA-256 pinning the run's input identity. **Honesty:** as in
  the [security-verdict](../v1/security-verdict.md), this pins *which* input was used, not that the input is
  exhaustive or adversarial; whether it is the approved set is an out-of-band auditor check.

- **`engine_commit`** (REQUIRED) - an auditor-pinnable identity of the engine/substrate the freeze
  ran at, in the spirit of an SLSA `builder.id`. **Honesty:** an identity to compare, not a means to
  re-derive the producer.

- **`fc_version`** (REQUIRED, string) - the hypervisor (Firecracker) version, so the pause-primitive
  cost numbers can be read against a known VMM build.

> Forward-compatibility: per the standard's rule, a verifier MUST ignore unknown fields inside the
> predicate and unknown entries inside `environment_attestations`. A producer MAY add fields
> additively within v2 (for example a hardware-attestation entry).

## Checklist verdict (out of band)

A producer SHOULD accompany the signed attestation with a non-signed, human-and-machine-readable
verdict document recording which freeze-atomicity checklist items the run **demonstrated** versus which
were **not demonstrated in this tier**. The checklist items are:

| Item | Property | Read from |
|---|---|---|
| A1 | per-VM netns + point-to-point `/31` veth | `topology.netns_per_vm`, `topology.veth_p2p_31` |
| A2 | single vsock Unix-domain socket reach per VM | host observation |
| A3 | strict reverse-path filter + bound source addr + spoof-drop proven | host observation |
| A4 | every escaped segment captured AND recipient `Paused` | `deltas.tx_escape` + `topology.ipv6_posture` |
| A5 | external-laundering precluded by default-deny egress | `egress_policy_digest` + host observation |
| B1 | boot-time byteident proofs separate from the termination snapshot | host observation |
| B2 | hypervisor `Queue::save` serializes scalar ring indices only (no in-flight payload) | source assertion |
| B3 | worst-case pause bounded (<= 30 s) and distributed | `deltas.fc_pause_ns` |

The verdict is OUT OF BAND (it is not the signed predicate). The hard honesty rule: a verdict MUST
mark any item the run did not measure as `NOT-DEMONSTRATED-THIS-TIER` - it MUST NOT tick an
un-demonstrated item passed, and MUST NOT fabricate a containment number for a tier that ran no
containment corpus. The signed predicate carries the *evidence* (the distributions, the digests, the
topology facts); the checklist verdict is a derived reading of that evidence plus host observations.

## `quiescence_sound`

`quiescence_sound` is the single boolean a downstream consumer (notably the
[a2a-mesh-scorecard](a2a-mesh-scorecard.md)) reads to mean "the freeze-atomicity tier for this mesh
was demonstrated sound." It is `true` iff the demonstrated checklist items (at minimum A4, B2, B3 on
real VMs) passed against the measured evidence. It is NOT carried as a standalone field of this
predicate; it is **derived** by a consumer from the checklist verdict over this attestation's
evidence, exactly as a scorecard consumer derives a display string from structured fields. A synthetic
or template attestation MUST NOT report a measured `quiescence_sound`; its flag is a template value
and the consuming scorecard labels it as such (see [a2a-mesh-scorecard](a2a-mesh-scorecard.md)).

## Verification (third-party, offline)

After the envelope checks in [signing-envelope.md](../v1/signing-envelope.md) succeed (signature, `keyid`,
`predicateType`, subject non-empty):

1. Confirm the `subject` digest equals the MeshManifest digest the verifier intends to bind to (the
   boot-time per-VM byteident root set), recomputing it from the served per-VM digests if available:
   `SHA-256(canonical-JSON-array(per-VM digests))`.
2. Confirm every `deltas` distribution carries the full `{p50, p90, p99, max, n}` key set, and that
   `deltas.tx_escape` carries `window_ns`, `escaped_segments` (>= 0), and `recipient_state_at_escape`.
3. Apply the atomicity rule: `recipient_state_at_escape == "Paused"`, every escaped segment accounted
   for by a `tcp_repair_queue_digests` entry, and `topology.ipv6_posture` a non-empty declared string.
4. Apply the bounded-pause rule: `deltas.fc_pause_ns.max <= 30e9` ns.
5. If the consumer has an auditor-approved `egress_policy_digest` and substrate identity, confirm the
   predicate's values equal them (value-binding, as in the [security-verdict](../v1/security-verdict.md)).
6. Resolve and re-hash the `mattern_ledger_sha256` ledger if the consumer's policy requires the
   net-zero-credit witness.

No live execution environment is required.

## What a verifier can and cannot independently check (honesty)

- A verifier CAN confirm the attestation is authentic, bound to its frozen-substrate subject, signed
  by a trusted key, and internally consistent (the distributions are well-formed, the atomicity and
  bounded-pause rules hold over the recorded numbers, and the pinned digests are present).
- A verifier CANNOT, from the attestation alone, confirm that the measured timing numbers were
  produced by a real freeze rather than asserted, nor that the host actually captured every escaped
  segment, nor that the `topology` booleans describe the real network setup. These are host
  self-assertions carried under the signature: the verifier learns the host *committed to* them. The
  attestation's guarantee is integrity, provenance, subject binding, and internal-rule consistency -
  not external re-execution of the freeze. The live-observation half that fills these inputs from real
  microVMs is the engine's job; this standard specifies the format it commits to.

## Why no perimeter sandbox can emit it (rationale)

This is the standards-capture point. The properties this predicate attests live below any
application- or network-perimeter interception layer:

- **The pause is a hypervisor primitive.** `fc_pause_ns` / `max_skew_ns` measure a `KVM` vCPU pause
  that halts the guest at the memory boundary. A syscall-shim or proxy sandbox has no quiescent-CPU
  primitive to time; it can stop forwarding traffic but cannot freeze the guest's execution state.
- **The escape evidence is host-side socket-buffer capture.** `tcp_repair_queue_digests` are read from
  the host's own view of the guest TCP queues at the cut point (a TCP-repair-mode snapshot). A sandbox
  that sees only the application's API calls has no host-side queue to snapshot.
- **The atomicity window is defined by the proxy-cut-to-pause gap.** `tx_escape` only has meaning when
  there is both a single inter-agent proxy *and* a hypervisor pause to bound the window between. A
  perimeter sandbox has neither boundary.

A competitor can copy this JSON shape, but it cannot fill `fc_pause_ns`, `max_skew_ns`, or a
host-captured `tx_escape` with real numbers without a hypervisor-boundary freeze and host-side socket
capture. The predicate format is open; the substrate that produces honest values for it is not
replicable at the perimeter.

## Status and maturity

- **Format and verification: stable, real.** The envelope, subject binding, distribution schema, and
  the offline-verify procedure are implemented and produce signed bundles that verify under the pinned
  key (see the conformance vectors in `conformance.json`).
- **Freeze-atomicity tier: live, partial.** The shipped signed bundle was produced from a real freeze
  run that measured `fc_pause_ns` / `max_skew_ns` / `proxy_stop_ns` on real microVMs and a `tx_escape`
  with `escaped_segments == 0` / recipient `Paused`. That tier demonstrates checklist items A4, B2, B3
  only. The network-containment items (A1/A2/A3/A5) and the boot-time-byteident item (B1) are
  **NOT-DEMONSTRATED in the freeze-atomicity tier** and belong to a separate integrated tier; the
  shipped verdict marks them as such and never ticks them passed.
- **Hardware host-trust root: roadmap.** `environment_attestations` carries `honest-assumed` today; a
  SEV-SNP/TDX quote or zkVM receipt is an additive future entry, not yet live.

## Related standards

- **[in-toto](https://github.com/in-toto/attestation) / [DSSE](https://github.com/secure-systems-lab/dsse)**
  - the envelope; see [signing-envelope.md](../v1/signing-envelope.md).
- **[SLSA VSA](https://slsa.dev/spec/v1.0/verification_summary)** - `engine_commit` follows the VSA
  `builder.id` idea (auditor-pinnable producer identity).
- **[a2a-mesh-scorecard](a2a-mesh-scorecard.md)** - the consumer that reads this attestation's
  freeze-atomicity soundness into a mesh composition-safety scorecard.

## Versioning

### Why v2 exists

v2 renames the engine-identity field to `engine_commit`. v1 spelled that field with a vendor-specific name, which a vendor-neutral standard other implementers are expected to emit must not require. Renaming a REQUIRED key is breaking under the rule stated below, so it takes a new predicateType URI rather than a silent in-place edit: one type URI never means two shapes. There is no alias and no dual-read compatibility path, and v1 is withdrawn - a verifier reads `engine_commit` or it rejects the statement.

### Rule

This is the mesh-quiescence v2 predicate. Adding a new optional field - including an additive
`environment_attestations` entry (a hardware quote) or an additive `topology` fact - is additive and
stays within v2; a verifier ignores fields it does not recognize. A rename or removal of a field, a
change to a distribution's required key set, or a change to the `tx_escape` shape is breaking and
requires a new major version.