humanish 0.107.0 → 0.108.0

package/dist/verify/shared-world-concurrent.js

@@ -1,8 +1,8 @@
 import { concurrencyFacts } from "../run/shared-world-evidence.js";
 import { COMMAND_DIGEST_PATTERN, SHARED_WORLD_STATESERIES_KEYS, planeProvenanceFindings, sharedWorldCommonFindings, } from "../run/shared-world-shape.js";
 import { isRecord } from "../run/type-guards.js";
-// CONCURRENT: the REQUIRED set (all must be present) AND a FORBIDDEN set (any present == a
-// sequential claim leaking into a concurrent bundle == overclaim). verify needs BOTH checks —
+// Concurrent: the required set (all must be present) and a forbidden set (any present == a
+// sequential claim leaking into a concurrent bundle == overclaim). verify needs both checks, because
 // presence-only would let an incoherent union pass.
 const CONCURRENT_REQUIRED_LIMITS = [
     "concurrent",
@@ -13,12 +13,12 @@ const CONCURRENT_REQUIRED_LIMITS = [
     "state-change-not-isolated-to-actors",
 ];
 const CONCURRENT_FORBIDDEN_LIMITS = ["sequential-only", "no-concurrent-races"];
-// EXTERNAL-PUBLIC plane class: the honest-downgrade required set. Keeps the concurrent family (an
-// honest ceiling) AND adds the mandatory disclosures for a plane the harness does NOT own: the
-// operator-attested (not harness-controlled) target, the ABSENCE of a synthetic attestation (you
-// cannot claim synthetic on a real site), the ABSENCE of an authoritative shared-state proof (no
-// in-sandbox filesystem to digest), and concurrency evidenced by temporal co-occupancy ONLY. Verify
-// FAILS CLOSED if any is missing (an absent honest-downgrade limit overclaims) — invariant 5.
+// External-public plane class: the downgrade required set. Keeps the concurrent family and adds
+// the mandatory disclosures for a plane the harness does not own: the
+// operator-attested target the harness does not control, the absence of a synthetic attestation (you
+// cannot claim synthetic on a real site), the absence of an authoritative shared-state proof (no
+// in-sandbox filesystem to digest), and concurrency evidenced by temporal co-occupancy only. Verify
+// fails closed if any is missing (an absent downgrade limit overclaims).
 const EXTERNAL_PUBLIC_EXTRA_LIMITS = [
     "external-public-plane",
     "operator-attested-target-not-harness-controlled",
@@ -26,7 +26,7 @@ const EXTERNAL_PUBLIC_EXTRA_LIMITS = [
     "no-authoritative-shared-state-proof",
     "concurrency-by-temporal-co-occupancy-only",
 ];
-// Any seeded/synthetic limit on this class is a getHost claim leaking onto a real public site — forbid
+// Any seeded/synthetic limit on this class is a getHost claim leaking onto a real public site; forbid
 // it alongside the sequential family. (A synthetic attestation on a plane the harness did not seed is a lie.)
 const EXTERNAL_PUBLIC_FORBIDDEN_LIMITS = [
     "sequential-only",
@@ -35,17 +35,17 @@ const EXTERNAL_PUBLIC_FORBIDDEN_LIMITS = [
     "synthetic",
 ];
 /**
- * CONCURRENT branch: N personas drove ONE getHost-exposed plane at once. Verify fail-closed: the
- * shape (laneWindows + stateSeries + outcomes, NO timeline); the required and forbidden
+ * Concurrent branch: N personas drove one getHost-exposed plane at once. Verify fail-closed: the
+ * shape (laneWindows + stateSeries + outcomes, no timeline); the required and forbidden
  * attributionLimits; the harness-minted getHost target every actor drove; the synthetic-subject
  * provenance gate; digest-only state series with the allowed-keys tripwire; single-plane
  * provenance; and the concurrency-on-pass gate (genuine overlap and a state delta at or after an
  * overlap start).
  */
 export function concurrentSharedWorldFindings(bundle, sw) {
-    // The PLANE-class discriminator. Absent means the provisioned-getHost plane. EVERY
+    // The plane-class discriminator. Absent means the provisioned-getHost plane. Every
     // getHost-specific assertion (hostDigest, exposure: synthetic, seeded provenance, state-delta on
-    // pass) is gated on this — it never leaks onto the external-public class, and the external-public
+    // pass) is gated on this, so it never leaks onto the external-public class, and the external-public
     // assertions never leak onto getHost.
     const planeClass = sw.planeClass;
     if (planeClass === "external-public") {
@@ -61,15 +61,15 @@ export function concurrentSharedWorldFindings(bundle, sw) {
 }
 const participantIdOf = (window) => typeof window.roleId === "string" ? window.roleId : "(unnamed)";
 /**
- * PROVISIONED-getHost concurrent branch: a clone/local-tree subject served and getHost-exposed
- * in-sandbox. The harness MINTED the host, so this asserts the synthetic-seeded attestation, the
+ * Provisioned-getHost concurrent branch: a clone/local-tree subject served and getHost-exposed
+ * in-sandbox. The harness minted the host, so this asserts the synthetic-seeded attestation, the
  * harness-minted host identity, and an authoritative in-sandbox checkpoint state-delta on pass.
  */
 function provisionedGetHostConcurrentFindings(bundle, sw) {
     const findings = sharedWorldCommonFindings(bundle, sw);
-    // Shape coherence: concurrent carries laneWindows/stateSeries/outcomes, NOT a timeline.
+    // Shape coherence: concurrent carries laneWindows/stateSeries/outcomes and no timeline.
     if (Array.isArray(sw.timeline)) {
-        findings.push("a concurrent shared-world bundle must NOT carry a sequential timeline (topologyMode mismatch)");
+        findings.push("a concurrent shared-world bundle must not carry a sequential timeline (topologyMode mismatch)");
     }
     const windows = recordsOf(sw.laneWindows);
     const stateSeries = recordsOf(sw.stateSeries);
@@ -83,10 +83,10 @@ function provisionedGetHostConcurrentFindings(bundle, sw) {
     if (windows === null || stateSeries === null || outcomes === null) {
         return findings; // can't reason further without the core series
     }
-    // Required limits all present AND forbidden limits all absent.
+    // Required limits all present and forbidden limits all absent.
     findings.push(...attributionLimitFindings(sw, CONCURRENT_REQUIRED_LIMITS, CONCURRENT_FORBIDDEN_LIMITS, {
-        missing: (limit) => `attributionLimits is missing the mandatory concurrent disclosure "${limit}" — an absent ceiling overclaims`,
-        forbidden: (limit) => `attributionLimits carries the forbidden disclosure "${limit}" — a concurrent run cannot claim a sequential guarantee`,
+        missing: (limit) => `attributionLimits is missing the required concurrent disclosure "${limit}"; without it the bundle claims more than the run can show`,
+        forbidden: (limit) => `attributionLimits carries the disclosure "${limit}", which a concurrent run cannot claim: it describes a sequential guarantee`,
     }), ...participantCoverageFindings(sw, windows, outcomes), ...windowFindings(bundle, windows, "the host it drove"), ...getHostPlaneFindings(bundle, sw, windows), ...stateSeriesFindings(stateSeries), ...concurrencyOnPassFindings(bundle, windows, stateSeries));
     return findings;
 }
@@ -103,7 +103,7 @@ function attributionLimitFindings(sw, required, forbidden, messages) {
 }
 /**
  * Phantom/dropped role: laneWindows + outcomes each cover exactly roleCount (actors are
- * INDEPENDENT — none are blocked by another, so all N produce a window + outcome).
+ * independent: none are blocked by another, so all N produce a window + outcome).
  */
 function participantCoverageFindings(sw, windows, outcomes) {
     const findings = [];
@@ -139,7 +139,7 @@ function windowFindings(bundle, windows, routeTarget) {
     return findings;
 }
 /**
- * The getHost plane: every actor drove EXACTLY the harness-minted host (invariant 2), the subject is
+ * The getHost plane: every actor drove exactly the harness-minted host, the subject is
  * attested synthetic and seeded, and every laneWindow shares the plane's provenance.
  */
 function getHostPlaneFindings(bundle, sw, windows) {
@@ -161,12 +161,12 @@ function getHostPlaneFindings(bundle, sw, windows) {
     // Synthetic-subject provenance gate (a getHost URL is internet-reachable; real/external data
     // behind it is the hazard). Author attestation + a seeded provenance check.
     if (plane.exposure !== "synthetic") {
-        findings.push('sharedWorld.plane.exposure must be "synthetic" — the getHost route requires the author attestation that the subject is synthetic seeded data (author-trust + provenance gate, not a no-real-data guarantee)');
+        findings.push('sharedWorld.plane.exposure must be "synthetic": the study must declare that a subject at a public sandbox URL holds synthetic seeded data. humanish records that declaration and cannot check it');
     }
     if (bundle.subject?.state.provenance !== "seeded") {
-        findings.push(`the concurrent getHost route requires subject.state.provenance == "seeded" (got "${bundle.subject?.state.provenance ?? "absent"}") — external/unpinned/undeclared data behind an internet-reachable URL is rejected`);
+        findings.push(`a provisioned shared-world run needs subject.state.provenance == "seeded" (got "${bundle.subject?.state.provenance ?? "absent"}"): external, unpinned or undeclared data at a public sandbox URL is not allowed`);
     }
-    // Single-plane provenance: every laneWindow shares ONE (commit, seedDigest) matching plane.
+    // Single-plane provenance: every laneWindow shares one (commit, seedDigest) matching plane.
     findings.push(...planeProvenanceFindings(windows, plane, {
         items: "laneWindows",
         item: "laneWindow",
@@ -174,7 +174,7 @@ function getHostPlaneFindings(bundle, sw, windows) {
     }));
     return findings;
 }
-/** stateSeries is DIGEST-ONLY with the allowed-keys tripwire (no per-delta→actor field). */
+/** stateSeries is digest-only with the allowed-keys tripwire (no per-delta→actor field). */
 function stateSeriesFindings(stateSeries) {
     const findings = [];
     for (const snapshot of stateSeries) {
@@ -186,7 +186,7 @@ function stateSeriesFindings(stateSeries) {
         }
         for (const key of Object.keys(snapshot)) {
             if (!SHARED_WORLD_STATESERIES_KEYS.has(key)) {
-                findings.push(`a stateSeries snapshot carries an unexpected field "${key}" — the series is digest-only (no per-delta attribution)`);
+                findings.push(`a stateSeries snapshot carries an unexpected field "${key}": the series holds digests only, with no attribution per change`);
             }
         }
     }
@@ -199,9 +199,9 @@ function participantWindows(windows) {
         : []);
 }
 /**
- * The concurrency-on-pass gate: a PASSED concurrent run MUST show genuine overlap (≥2 laneWindows
- * overlapping in time) AND a stateSeries delta whose timestamp is AT/AFTER the start of an
- * overlap interval — otherwise it was not actually concurrent, or the world never changed under
+ * The concurrency-on-pass gate: a passed concurrent run must show genuine overlap (≥2 laneWindows
+ * overlapping in time) and a stateSeries delta whose timestamp is at or after the start of an
+ * overlap interval. Otherwise it was not actually concurrent, or the world never changed under
  * contention (a hollow concurrent claim). The facts come from concurrencyFacts, which the judge
  * also reads.
  */
@@ -213,32 +213,32 @@ function concurrencyOnPassFindings(bundle, windows, stateSeries) {
         : []));
     if (!facts.overlap) {
         return [
-            "review verdict is pass but no two laneWindows overlap in time — the run was not actually concurrent",
+            "the review verdict is pass, but no two laneWindows overlap in time, so the participants did not run at once",
         ];
     }
     if (facts.stateChangedUnderOverlap === true)
         return [];
     return [
-        "review verdict is pass but no stateSeries delta occurs at/after an overlap interval start — the shared world did not change under concurrent load (hollow concurrent claim)",
+        "the review verdict is pass, but no stateSeries change happens at or after the start of an overlap, so the shared app did not change while the participants ran together",
     ];
 }
 /**
- * EXTERNAL-PUBLIC concurrent branch: N seats drove ONE real operator-owned public deployment at
- * once. The honest evidence class for a plane the harness does NOT own. Verify fail-closed on the
- * honest DOWNGRADES (asserted-absent, never silently dropped): provenance is "external-public" (NOT
- * seeded), exposure is ABSENT (claiming synthetic on a real site is a lie), plane control is
- * operator-attested (publicOriginDigest, not a harness-minted hostDigest), there is NO
+ * External-public concurrent branch: N participants drove one real operator-owned public deployment
+ * at once. The evidence class for a plane the harness does not own. Verify fails closed on the
+ * downgrades (asserted-absent, never silently dropped): provenance is "external-public" (never
+ * seeded), exposure is absent (claiming synthetic on a real site would be false), plane control is
+ * operator-attested (publicOriginDigest; there is no harness-minted hostDigest), there is no
  * authoritative shared-state proof (stateSeries omitted), and concurrency is proven by temporal
- * co-occupancy ONLY (relaxed concurrency-on-pass: ≥2 overlapping windows, no state delta). Every
+ * co-occupancy only (relaxed concurrency-on-pass: ≥2 overlapping windows, no state delta). Every
  * getHost-only claim (exposure: synthetic / plane.hostDigest / seeded / synthetic limit) appearing
- * here FAILS CLOSED.
+ * here fails closed.
  */
 function externalPublicConcurrentFindings(bundle, sw) {
     const findings = sharedWorldCommonFindings(bundle, sw);
-    // Shape coherence: concurrent carries laneWindows + outcomes, NOT a timeline. stateSeries is
-    // deliberately OMITTED on this class (no in-sandbox filesystem to authoritatively digest).
+    // Shape coherence: concurrent carries laneWindows + outcomes and no timeline. stateSeries is
+    // deliberately omitted on this class (no in-sandbox filesystem to authoritatively digest).
     if (Array.isArray(sw.timeline)) {
-        findings.push("an external-public concurrent bundle must NOT carry a sequential timeline (topologyMode mismatch)");
+        findings.push("an external-public concurrent bundle must not carry a sequential timeline (topologyMode mismatch)");
     }
     const windows = recordsOf(sw.laneWindows);
     const outcomes = recordsOf(sw.outcomes);
@@ -246,87 +246,89 @@ function externalPublicConcurrentFindings(bundle, sw) {
         findings.push("an external-public concurrent bundle must carry laneWindows");
     if (outcomes === null)
         findings.push("an external-public concurrent bundle must carry outcomes");
-    // NO authoritative shared-state proof: a non-empty stateSeries would falsely imply the harness
+    // No authoritative shared-state proof: a non-empty stateSeries would falsely imply the harness
     // digested the plane's backend state (it cannot; there is no in-sandbox filesystem).
     const stateSeries = sw.stateSeries;
     if (Array.isArray(stateSeries) && stateSeries.length > 0) {
-        findings.push("an external-public concurrent bundle must NOT carry a stateSeries — the harness cannot authoritatively digest a real public plane's backend state (no in-sandbox filesystem); concurrency is proven by temporal co-occupancy, not a state series");
+        findings.push("an external-public concurrent bundle must not carry a stateSeries: humanish cannot read the state of a public deployment it does not run, so this route shows concurrency by overlapping sessions instead");
     }
     if (windows === null || outcomes === null) {
         return findings; // can't reason further without the core series
     }
-    // Attribution ceiling: the concurrent family AND every external-public honest-downgrade disclosure
+    // Attribution ceiling: the concurrent family and every external-public downgrade disclosure
     // must be present; the sequential family + any seeded/synthetic limit must be absent.
     findings.push(...attributionLimitFindings(sw, [...CONCURRENT_REQUIRED_LIMITS, ...EXTERNAL_PUBLIC_EXTRA_LIMITS], EXTERNAL_PUBLIC_FORBIDDEN_LIMITS, {
-        missing: (limit) => `attributionLimits is missing the mandatory external-public disclosure "${limit}" — an absent honest-downgrade ceiling overclaims`,
-        forbidden: (limit) => `attributionLimits carries the forbidden disclosure "${limit}" — the external-public plane cannot claim a sequential guarantee or a seeded/synthetic attestation on a real site`,
+        missing: (limit) => `attributionLimits is missing the required external-public disclosure "${limit}"; without it the bundle claims more than the run can show`,
+        forbidden: (limit) => `attributionLimits carries the disclosure "${limit}", which an external-public run cannot claim: it describes a sequential guarantee or seeded synthetic data, and the app is a real deployment`,
     }), ...participantCoverageFindings(sw, windows, outcomes), ...windowFindings(bundle, windows, "the origin it reached"), ...externalPublicPlaneFindings(bundle, sw, windows));
-    // The RELAXED concurrency-on-pass gate: a PASSED external-public run MUST show genuine temporal
-    // co-occupancy (≥2 laneWindows overlapping in time). There is NO state-delta requirement — the
+    // The relaxed concurrency-on-pass gate: a passed external-public run must show genuine temporal
+    // co-occupancy (≥2 laneWindows overlapping in time). There is no state-delta requirement: the
     // observed co-occupancy of one declared origin (plus the optional lobby convergence) carries the
     // "they shared a world" claim, disclosed as concurrency-by-temporal-co-occupancy-only.
     if (bundle.review.verdict === "pass" &&
         !concurrencyFacts(participantWindows(windows), undefined).overlap) {
-        findings.push("review verdict is pass but no two laneWindows overlap in time — the external-public run was not actually concurrent (concurrency is proven by temporal co-occupancy on this class)");
+        findings.push("the review verdict is pass, but no two laneWindows overlap in time, so the participants of this external-public run did not run at once");
     }
     return findings;
 }
 /**
- * The external-public plane (the honest analog of invariant 2, WEAKER + disclosed): the seats
- * converged on one OBSERVED origin, nothing claims harness control or a synthetic seeded subject,
- * and every laneWindow shares the plane's provenance.
+ * The external-public plane (the counterpart of the harness-minted-URL rule, with a weaker,
+ * disclosed claim): the participants converged on one observed origin, nothing claims harness
+ * control or a synthetic seeded subject, and every laneWindow shares the plane's provenance.
  */
 function externalPublicPlaneFindings(bundle, sw, windows) {
     const findings = [];
-    // The convergence proof is about what the seats OBSERVED, not what was DECLARED.
-    // plane.publicOriginDigest is the OBSERVED origin the seats converged on; verify requires every
-    // seat's CDP-OBSERVED routeHostDigest to agree on ONE origin, and that publicOriginDigest BE that
-    // origin. Convergence on one observed origin proves inter-seat co-location — NOT harness control
-    // of the plane. IMPORTANT: operator OWNERSHIP rests on the subject.publicTarget.authorized
-    // attestation + the declared appUrl, NOT on digest equality — a normal cross-origin redirect
-    // (apex->www, http->https) makes the observed origin differ from the DECLARED one, which is
-    // expected and must NEVER fail verify (declaredOriginDigest is evidence-only).
+    // The convergence proof is about what the participants observed; the declared origin is not part
+    // of it. plane.publicOriginDigest is the observed origin the participants converged on; verify
+    // requires every participant's CDP-observed routeHostDigest to agree on one origin, and that
+    // publicOriginDigest be that origin. Convergence on one observed origin proves cross-participant
+    // co-location. It does not prove harness control of the plane. Operator ownership rests on the
+    // subject.publicTarget.authorized attestation + the declared appUrl. Digest equality plays no
+    // part, because a normal cross-origin redirect (apex->www, http->https) makes the observed origin
+    // differ from the declared one, which is expected and must never fail verify
+    // (declaredOriginDigest is evidence-only).
     const plane = isRecord(sw.plane) ? sw.plane : {};
     const publicOriginDigest = typeof plane.publicOriginDigest === "string" ? plane.publicOriginDigest : undefined;
     if (!publicOriginDigest || !COMMAND_DIGEST_PATTERN.test(publicOriginDigest)) {
-        findings.push("sharedWorld.plane.publicOriginDigest (sha256-16 of the OBSERVED origin the participants converged on) is required on the external-public plane class");
+        findings.push("sharedWorld.plane.publicOriginDigest (the sha256-16 of the origin the participants were observed to reach) is required on an external-public run");
     }
-    // The observed origins across seats must agree on exactly ONE (that agreement IS the convergence).
+    // The observed origins across participants must agree on exactly one (that agreement is the
+    // convergence).
     const observedOrigins = windows
         .map((window) => typeof window.routeHostDigest === "string" ? window.routeHostDigest : undefined)
         .filter((digest) => digest !== undefined);
     const distinctObserved = [...new Set(observedOrigins)];
     if (distinctObserved.length > 1) {
-        findings.push(`the participants did not converge on ONE OBSERVED origin; distinct observed origin digests: ${distinctObserved.join(", ")}`);
+        findings.push(`the participants were observed on more than one origin; observed origin digests: ${distinctObserved.join(", ")}`);
     }
     else if (publicOriginDigest &&
         distinctObserved.length === 1 &&
         distinctObserved[0] !== publicOriginDigest) {
-        findings.push(`sharedWorld.plane.publicOriginDigest (${publicOriginDigest}) must equal the single OBSERVED origin the participants converged on (${distinctObserved[0]})`);
+        findings.push(`sharedWorld.plane.publicOriginDigest (${publicOriginDigest}) must equal the one origin the participants were observed to reach (${distinctObserved[0]})`);
     }
-    // declaredOriginDigest is recorded for evidence ONLY. Validate its shape when present, but NEVER
-    // assert it equals the observed origin — a cross-origin redirect is normal and expected.
+    // declaredOriginDigest is recorded for evidence only. Validate its shape when present, but never
+    // assert it equals the observed origin: a cross-origin redirect is normal and expected.
     if (plane.declaredOriginDigest !== undefined &&
         (typeof plane.declaredOriginDigest !== "string" ||
             !COMMAND_DIGEST_PATTERN.test(plane.declaredOriginDigest))) {
         findings.push("sharedWorld.plane.declaredOriginDigest, when present, must be a sha256-16 digest of the operator-declared origin (evidence-only; not asserted equal to the observed origin)");
     }
-    // INVERT the getHost gate: exposure MUST be absent (claiming synthetic on a real site is a lie) and
-    // the harness-minted hostDigest MUST be absent (the harness minted no host here).
+    // Invert the getHost gate: exposure must be absent (claiming synthetic on a real site would be false) and
+    // the harness-minted hostDigest must be absent (the harness minted no host here).
     if (plane.exposure !== undefined) {
-        findings.push('sharedWorld.plane.exposure must be ABSENT on the external-public plane class — the harness neither provisioned nor exposed the plane, so it cannot attest "synthetic" on a real site');
+        findings.push('sharedWorld.plane.exposure must be absent on an external-public run: humanish did not provision the app, so it cannot declare a real deployment "synthetic"');
     }
     if (plane.hostDigest !== undefined) {
-        findings.push("sharedWorld.plane.hostDigest must be ABSENT on the external-public plane class — a harness-minted host identity is a getHost claim; this plane is operator-attested, not harness-minted");
+        findings.push("sharedWorld.plane.hostDigest must be absent on an external-public run: it records a sandbox URL humanish created, and this app is a deployment the operator declared");
     }
-    // Provenance is the external-public marker: NOT seeded (nothing was seeded), NOT unpinned.
+    // Provenance is the external-public marker, which is neither seeded (nothing was seeded) nor unpinned.
     if (bundle.subject?.state.provenance !== "external-public") {
-        findings.push(`the external-public plane class requires subject.state.provenance == "external-public" (got "${bundle.subject?.state.provenance ?? "absent"}") — a seeded/unpinned/undeclared claim on an operator-owned public deployment is dishonest`);
+        findings.push(`an external-public run needs subject.state.provenance == "external-public" (got "${bundle.subject?.state.provenance ?? "absent"}"): seeded, unpinned or undeclared does not describe a public deployment the operator runs`);
     }
     if (bundle.subject?.source !== "app-url") {
-        findings.push('the external-public plane class requires subject.source == "app-url" — the plane is a real public deployment, not a provisioned subject');
+        findings.push('an external-public run needs subject.source == "app-url": the app is a public deployment, not a subject humanish provisions');
     }
-    // Single-plane provenance: every laneWindow shares ONE (commit, seedDigest) matching plane. commit
+    // Single-plane provenance: every laneWindow shares one (commit, seedDigest) matching plane. commit
     // is absent on this class (nothing cloned); seedDigest is the constant empty-recipe digest.
     findings.push(...planeProvenanceFindings(windows, plane, {
         items: "laneWindows",
@@ -334,7 +336,8 @@ function externalPublicPlaneFindings(bundle, sw, windows) {
         run: "shared-world",
     }));
     // The lobby-convergence proof (optional-but-strong): if present it must be a sha256-16 digest of the
-    // shared /lobby/CODE path all seats converged on (digest-only; the raw CODE never lands).
+    // shared `/lobby/CODE` path all participants converged on (digest-only; the raw lobby code never
+    // lands).
     const lobbyConvergenceDigest = sw
         .lobbyConvergenceDigest;
     if (lobbyConvergenceDigest !== undefined &&

package/dist/verify/shared-world.d.ts

@@ -1,7 +1,7 @@
 import type { RunBundle } from "../run/bundle.js";
 /**
- * The `shared-world evidence` check (invariant 4 + invariant 6): a LIVE shared-world bundle's
- * interaction CLAIM must match its recorded timeline + plane provenance, and its attribution
+ * The `shared-world evidence` check: a live shared-world bundle's
+ * interaction claim must match its recorded timeline + plane provenance, and its attribution
  * ceiling must be pinned. Mirrors validateTerminalProductEvidence: live-only (dry-run contract
  * bundles are skipped, exactly like the other live-only checks). Fail-closed on every overclaim.
  */

package/dist/verify/shared-world.js

@@ -2,8 +2,8 @@ import { COMMAND_DIGEST_PATTERN, MANDATORY_ATTRIBUTION_LIMITS, SHARED_WORLD_CHEC
 import { isRecord } from "../run/type-guards.js";
 import { concurrentSharedWorldFindings } from "./shared-world-concurrent.js";
 /**
- * The `shared-world evidence` check (invariant 4 + invariant 6): a LIVE shared-world bundle's
- * interaction CLAIM must match its recorded timeline + plane provenance, and its attribution
+ * The `shared-world evidence` check: a live shared-world bundle's
+ * interaction claim must match its recorded timeline + plane provenance, and its attribution
  * ceiling must be pinned. Mirrors validateTerminalProductEvidence: live-only (dry-run contract
  * bundles are skipped, exactly like the other live-only checks). Fail-closed on every overclaim.
  */
@@ -15,13 +15,13 @@ export function sharedWorldEvidenceFindings(bundle) {
     }
     const sw = bundle.sharedWorld;
     if (!sw) {
-        // A live bundle that DECLARES shared-world attribution but carries no evidence block is a
-        // hollow claim — fail closed. (Absent attributionClass + absent block == an ordinary bundle.)
+        // A live bundle that declares shared-world attribution but carries no evidence block is a
+        // hollow claim, so it fails closed. (Absent attributionClass + absent block == an ordinary bundle.)
         return bundle.attributionClass === "shared-world"
             ? ["attributionClass is shared-world but the sharedWorld evidence block is missing"]
             : [];
     }
-    // Dispatch on topologyMode FIRST; unknown/missing → fail closed.
+    // Dispatch on topologyMode first; unknown/missing → fail closed.
     const topologyMode = sw.topologyMode;
     if (topologyMode !== "sequential" && sw.skippedTail !== undefined) {
         return ["skippedTail is only valid on sequential shared-world evidence"];
@@ -33,7 +33,7 @@ export function sharedWorldEvidenceFindings(bundle) {
         return concurrentSharedWorldFindings(bundle, sw);
     }
     return [
-        'sharedWorld.topologyMode must be "sequential" or "concurrent" (missing/unknown → fail closed)',
+        'sharedWorld.topologyMode must be "sequential" or "concurrent"; a missing or unknown value fails verification',
     ];
 }
 /** Validate the declared suffix against the executed prefix and existing participant evidence. */
@@ -186,8 +186,8 @@ function runSpendLimitRecorded(bundle, turns, tail) {
         sum > tail.maxTotalUsd);
 }
 /**
- * SEQUENTIAL branch: the alternating timeline must be well-formed, single-plane, digest-only, and
- * carry the sequential attributionLimits. A sequential bundle must NOT carry concurrent fields
+ * Sequential branch: the alternating timeline must be well-formed, single-plane, digest-only, and
+ * carry the sequential attributionLimits. A sequential bundle must not carry concurrent fields
  * (laneWindows).
  */
 function sequentialSharedWorldFindings(bundle, sw) {
@@ -201,14 +201,14 @@ function sequentialSharedWorldFindings(bundle, sw) {
         findings.push("a sequential shared-world bundle must carry a timeline");
     }
     if (Array.isArray(sw.laneWindows)) {
-        findings.push("a sequential shared-world bundle must NOT carry concurrent laneWindows (topologyMode mismatch)");
+        findings.push("a sequential shared-world bundle must not carry concurrent laneWindows (topologyMode mismatch)");
     }
     const sequence = Array.isArray(sw.sequence) ? sw.sequence : [];
-    // Attribution ceiling: every mandatory limit MUST be present (omission overclaims → fail).
+    // Attribution ceiling: every mandatory limit must be present (omission overclaims → fail).
     const limits = Array.isArray(sw.attributionLimits) ? sw.attributionLimits : [];
     for (const required of MANDATORY_ATTRIBUTION_LIMITS) {
         if (!limits.includes(required)) {
-            findings.push(`attributionLimits is missing the mandatory disclosure "${required}" — an absent ceiling overclaims`);
+            findings.push(`attributionLimits is missing the required disclosure "${required}"; without it the bundle claims more than the run can show`);
         }
     }
     const checkpoints = rawTimeline.filter((entry) => isRecord(entry) && entry.kind === "checkpoint");
@@ -256,7 +256,7 @@ function sequentialSharedWorldFindings(bundle, sw) {
             }
         }
     });
-    // Checkpoints: digest is sha256-16 and the record carries NO value-shaped field (digest-only).
+    // Checkpoints: digest is sha256-16 and the record carries no value-shaped field (digest-only).
     for (const checkpoint of checkpoints) {
         const name = typeof checkpoint.name === "string" ? checkpoint.name : "(unnamed)";
         if (typeof checkpoint.digest !== "string" || !COMMAND_DIGEST_PATTERN.test(checkpoint.digest)) {
@@ -264,7 +264,7 @@ function sequentialSharedWorldFindings(bundle, sw) {
         }
         for (const key of Object.keys(checkpoint)) {
             if (!SHARED_WORLD_CHECKPOINT_KEYS.has(key)) {
-                findings.push(`checkpoint "${name}" carries an unexpected field "${key}" — checkpoints persist digest-only`);
+                findings.push(`checkpoint "${name}" carries an unexpected field "${key}": checkpoints store digests only`);
             }
         }
     }
@@ -278,18 +278,18 @@ function sequentialSharedWorldFindings(bundle, sw) {
             findings.push(`turn "${participantId}" references unknown streamId "${String(turn.streamId)}"`);
         }
     }
-    // Single-plane provenance: every turn shares ONE (commit, seedDigest), matching sharedWorld.plane.
+    // Single-plane provenance: every turn shares one (commit, seedDigest), matching sharedWorld.plane.
     // (plane.seedDigest + plane.envNames shape are checked in sharedWorldCommonFindings.)
     findings.push(...planeProvenanceFindings(turns, sw.plane, {
         items: "turns",
         item: "turn",
         run: "shared-world",
     }));
-    // The delta-on-pass gate: a PASSED shared-world run MUST show at least one checkpoint delta —
+    // The delta-on-pass gate: a passed shared-world run must show at least one checkpoint delta;
     // otherwise the roles never interacted through shared state and the claim is hollow.
     if (bundle.review.verdict === "pass" &&
         !checkpoints.some((checkpoint) => checkpoint.deltaFromPrev === true)) {
-        findings.push("review verdict is pass but no checkpoint shows deltaFromPrev — the interaction is hollow (no observed shared-state change)");
+        findings.push("the review verdict is pass, but no checkpoint shows deltaFromPrev, so no change to the shared app was observed");
     }
     return findings;
 }

package/dist/verify/subject.d.ts

@@ -1,6 +1,6 @@
 import type { RunBundle } from "../run/bundle.js";
 /**
- * The `subject state provenance` check (invariant 5 + invariant 4): a bundle's subject CLAIM
+ * The `subject state provenance` check: a bundle's subject claim
  * must match its recorded evidence. A bundle without a subject block passes untouched.
  * Live-vs-dry-run is judged from bundle.mode, exactly like
  * noEngagementActorFindings. Covers both the state story (seed/external) and, for the
@@ -8,10 +8,10 @@ import type { RunBundle } from "../run/bundle.js";
  */
 export declare function subjectStateFindings(bundle: RunBundle): string[];
 /**
- * Advisory (never flips ok): a LIVE clone bundle whose subject env is provisioned while its
+ * Advisory (never flips ok): a live clone bundle whose subject env is provisioned while its
  * state story is undeclared probably points at state the lab does not control. Emitted at
- * most ONCE per bundle (the subject block is bundle-level, never per stream). GITHUB_TOKEN
- * is mechanically excluded: the harness consumes that name for clone auth — it carries no
+ * most once per bundle (the subject block is bundle-level, never per stream). GITHUB_TOKEN
+ * is mechanically excluded: the harness consumes that name for clone auth, and it carries no
  * state implication.
  */
 export declare function undeclaredSubjectStateWarnings(bundle: RunBundle): string[];

package/dist/verify/subject.js

@@ -3,7 +3,7 @@
 import { COMMAND_DIGEST_PATTERN, SUBJECT_ENV_NAME_PATTERN } from "../run/shared-world-shape.js";
 import { ARCHIVE_SHA256_PATTERN } from "../run/bundle-shape.js";
 /**
- * The `subject state provenance` check (invariant 5 + invariant 4): a bundle's subject CLAIM
+ * The `subject state provenance` check: a bundle's subject claim
  * must match its recorded evidence. A bundle without a subject block passes untouched.
  * Live-vs-dry-run is judged from bundle.mode, exactly like
  * noEngagementActorFindings. Covers both the state story (seed/external) and, for the
@@ -18,34 +18,34 @@ export function subjectStateFindings(bundle) {
     const state = subject.state;
     const seed = state.seed ?? [];
     const live = bundle.mode === "live";
-    // Local-tree fail-closed pin: a LIVE local-tree subject must carry a well-formed archive
-    // digest -- a dirty tree cannot be commit-pinned, so archiveSha256 is the only content pin
+    // Local-tree fail-closed pin: a live local-tree subject must carry a well-formed archive
+    // digest: a dirty tree cannot be commit-pinned, so archiveSha256 is the only content pin
     // this route has. Mirrors the seeded-on-dry-run discriminator immediately below: judged by
     // bundle.mode, never by the presence/shape of other fields. Never echoes the malformed value
     // (it could itself be a leaked value, same discipline as the externalEnvNames check below).
     if (live && subject.source === "local-tree") {
         // Note: a malformed-but-present string is already rejected upstream by the
         // isRunSubjectProvenance shape gate, so in practice this branch fires for the
-        // MISSING case; the pattern re-check stays as defense in depth for callers
+        // missing case; the pattern re-check stays as defense in depth for callers
         // that bypass the schema gate.
         const pin = subject.archiveSha256;
         if (typeof pin !== "string" || !ARCHIVE_SHA256_PATTERN.test(pin)) {
             findings.push("subject.source is local-tree on a live run but archiveSha256 is missing or malformed (a local-tree subject must carry a well-formed 64-hex archive digest)");
         }
     }
-    // Marker-independent rule: a passed LIVE run can never ride on a seed step that did not
-    // complete ok (closes the hollow-seeded × unpinned hole — an unpinned bundle still carries
+    // Marker-independent rule: a passed live run can never ride on a seed step that did not
+    // complete ok (closes the hollow-seeded × unpinned hole: an unpinned bundle still carries
     // its seed records, and a failed migration must not hide behind the external marker).
     if (live && bundle.review.verdict === "pass" && seed.some((record) => record.ok !== true)) {
-        findings.push("review verdict is pass but a recorded seed step did not complete ok — a passed live run cannot carry failed or unexecuted state steps");
+        findings.push("the review verdict is pass, but a recorded seed step did not complete; a passed live run cannot have failed or skipped state steps");
     }
     switch (state.provenance) {
         case "seeded": {
             if (!live) {
-                findings.push('state marker "seeded" on a dry-run bundle — a contract bundle cannot claim executed state');
+                findings.push('state marker "seeded" on a dry-run bundle: a dry run executes no state steps');
             }
             if (seed.length === 0) {
-                findings.push('state marker "seeded" with zero seed step records is a hollow state claim');
+                findings.push('state marker "seeded" with no seed step records claims state the run did not set up');
             }
             for (const record of seed) {
                 if (!COMMAND_DIGEST_PATTERN.test(record.commandDigest)) {
@@ -64,8 +64,8 @@ export function subjectStateFindings(bundle) {
             }
             for (const name of externalEnvNames) {
                 if (!SUBJECT_ENV_NAME_PATTERN.test(name)) {
-                    // Deliberately does NOT echo the entry: a malformed entry may BE a value.
-                    findings.push("externalEnvNames carries an entry that is not an env var NAME shape (values must never appear in evidence)");
+                    // Deliberately does not echo the entry: a malformed entry may be a value.
+                    findings.push("externalEnvNames has an entry that is not an environment variable name; evidence may hold names only, never values");
                 }
             }
             break;
@@ -83,13 +83,13 @@ export function subjectStateFindings(bundle) {
             // nor seeded. It has no in-sandbox state story, so a seed record or an external channel here
             // contradicts the "no subject sandbox" invariant of this plane class.
             if (subject.source !== "app-url") {
-                findings.push('state marker "external-public" requires subject.source "app-url" — the external-public plane is a real public deployment, not a clone/local-tree subject');
+                findings.push('state marker "external-public" needs subject.source "app-url": an external-public app is a public deployment, not a clone or local-tree subject');
             }
             if (seed.length > 0) {
-                findings.push('state marker "external-public" cannot carry seed step records — the external-public plane is neither provisioned nor seeded by the harness');
+                findings.push('state marker "external-public" cannot carry seed step records: humanish neither provisions nor seeds a public deployment');
             }
             if ((state.externalEnvNames ?? []).length > 0) {
-                findings.push('state marker "external-public" cannot carry externalEnvNames — the plane is operator-owned, not an uncontrolled external channel');
+                findings.push('state marker "external-public" cannot carry externalEnvNames: the operator runs this app, so there is no external state to declare');
             }
             break;
         }
@@ -99,10 +99,10 @@ export function subjectStateFindings(bundle) {
     return findings;
 }
 /**
- * Advisory (never flips ok): a LIVE clone bundle whose subject env is provisioned while its
+ * Advisory (never flips ok): a live clone bundle whose subject env is provisioned while its
  * state story is undeclared probably points at state the lab does not control. Emitted at
- * most ONCE per bundle (the subject block is bundle-level, never per stream). GITHUB_TOKEN
- * is mechanically excluded: the harness consumes that name for clone auth — it carries no
+ * most once per bundle (the subject block is bundle-level, never per stream). GITHUB_TOKEN
+ * is mechanically excluded: the harness consumes that name for clone auth, and it carries no
  * state implication.
  */
 export function undeclaredSubjectStateWarnings(bundle) {
@@ -118,6 +118,6 @@ export function undeclaredSubjectStateWarnings(bundle) {
         return [];
     }
     return [
-        `Subject env is provisioned (${stateRelevantEnvNames.join(", ")}) but no state story is declared; if any name points at external state, declare subject.state.external (recorded UNPINNED) or seed in-sandbox state with subject.state.seed.`,
+        `Subject env is provisioned (${stateRelevantEnvNames.join(", ")}) but no state is declared. If a name points at external state, declare it in subject.state.external (recorded as unpinned), or seed the state in the sandbox with subject.state.seed.`,
     ];
 }