fix(chain): carry structured authz facts on the error + cover the author-aware reroute probe (#1689)

Two review findings from PR #1971.

PublisherNotAuthorizedForContextGraphError accepted the structured
diagnostic details, rendered a message from them, then dropped several.
A consumer asking the very next question -- "is this chain simply not
rotated yet, or was the author checked and refused?" -- had to parse
`error.message` for facts the adapter had already computed exactly once.
This PR exists to remove that coupling, so re-introducing it one question
later was self-defeating. The error now carries the full (frozen) details
object; `code`, the message contract and the flattened convenience fields
are unchanged, so publisher's classifier and existing consumers are
unaffected.

The author-aware `poolHasFundableSigner` call in
`enrichInsufficientPublisherFundsError` had no test. Dropping the author
argument there would leave every existing test green while silently
turning a recoverable author-authorized reroute into a terminal
NO_FUNDED_PUBLISHER_WALLET -- the same shape as the dkg-publisher.ts
forwarding line the adversarial review caught. Now covered, with a
payer-only negative control proving the legacy path is unchanged.

Chain unit suite 853 -> 857 passing. Closure build clean.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Jurij89

packages/chain/src/evm-adapter-errors.ts

@@ -434,23 +434,49 @@ export interface PublisherNotAuthorizedForCgDetails {
  * `authority_forbidden` instead of falling through to the retryable
  * `rpc_unavailable` default that made this failure loop to `maxRetries`. Same
  * shape and convention as {@link InsufficientPublisherFundsError}.
+ *
+ * Carries the FULL {@link PublisherNotAuthorizedForCgDetails} it was built from, not
+ * just the fields the message happens to render. The gate computes those facts
+ * exactly once at throw time; without them on the object, a consumer asking the very
+ * next question — *"is this chain simply not rotated yet, or was the author checked
+ * and refused?"* — would have to parse `message`. This PR exists to remove exactly
+ * that coupling, so re-introducing it one question later would be self-defeating.
+ * The message stays the human surface; `details` is the machine surface.
  */
 export class PublisherNotAuthorizedForContextGraphError extends Error {
   readonly code = PUBLISHER_NOT_AUTHORIZED_FOR_CG_CODE;
+
+  /**
+   * The exact facts the message was rendered from — frozen, so a consumer cannot
+   * mutate one error's diagnosis and have it disagree with its own text.
+   * `attestedAuthorConsidered` + `deployedLifecycleVersion` are the pair worth
+   * reading: together they separate "author refused" from "author never weighed
+   * because the lifecycle predates the capability (or its version was unreadable)".
+   */
+  readonly details: PublisherNotAuthorizedForCgDetails;
+
+  // Flattened conveniences, retained so existing consumers keep compiling.
   readonly contextGraphId: bigint;
   readonly payerAddress: string;
   readonly payerPoolAddresses?: readonly string[];
   readonly attestedAuthorAddress?: string;
+
   constructor(
     message: string,
     details: PublisherNotAuthorizedForCgDetails,
     options?: { cause?: unknown },
   ) {
     super(message, options);
     this.name = 'PublisherNotAuthorizedForContextGraphError';
+    this.details = Object.freeze({
+      ...details,
+      payerPoolAddresses: details.payerPoolAddresses
+        ? Object.freeze([...details.payerPoolAddresses])
+        : undefined,
+    });
     this.contextGraphId = details.contextGraphId;
     this.payerAddress = details.payerAddress;
-    this.payerPoolAddresses = details.payerPoolAddresses;
+    this.payerPoolAddresses = this.details.payerPoolAddresses;
     this.attestedAuthorAddress = details.attestedAuthorAddress;
   }
 }

packages/chain/test/evm-adapter-publish-admission.unit.test.ts

@@ -27,6 +27,7 @@ import { describe, it, expect } from 'vitest';
 import { ethers } from 'ethers';
 import {
   EVMChainAdapter,
+  InsufficientPublisherFundsError,
   PublisherNotAuthorizedForContextGraphError,
   isPublisherNotAuthorizedForCgError,
   formatPublisherNotAuthorizedForCgMessage,
@@ -39,6 +40,7 @@ import { PUBLISHER_NOT_AUTHORIZED_FOR_CG_CODE } from '@origintrail-official/dkg-
 
 const CG = 7n;
 const AUTHOR = '0x1111111111111111111111111111111111111111';
+const lc = (s: string) => s.toLowerCase();
 const PK_A = `0x${'1'.repeat(64)}`;
 const PK_B = `0x${'2'.repeat(64)}`;
 
@@ -162,6 +164,48 @@ describe('#1689 publish admission — diagnostic accuracy [CH-1689-D]', () => {
     );
     expect(error.message).toContain(`deployed version is ${BELOW_THRESHOLD}`);
   });
+
+  // The facts are computed ONCE at throw time. If they live only in the rendered
+  // message, the next consumer question — "not rotated yet, or author refused?" —
+  // forces message-parsing, which is the exact coupling this PR removes. So the
+  // thrown object must expose what the formatter was given, and the two must agree.
+  it('the thrown error carries the structured facts its message was rendered from', async () => {
+    const { a } = makeAdapter([AUTHOR.toLowerCase()], BELOW_THRESHOLD);
+    const payer = a.signerPool[0].address;
+
+    const error = await caught(() => a.resolvePinnedPublisherSigner(CG, payer, AUTHOR));
+
+    // The two fields that answer the question without touching `message`.
+    expect(error.details.attestedAuthorConsidered).toBe(false);
+    expect(error.details.deployedLifecycleVersion).toBe(BELOW_THRESHOLD);
+    expect(error.details.minLifecycleVersion).toBe(ATTESTED_AUTHOR_PUBLISH_AUTHZ_MIN_KAL_VERSION);
+    expect(error.details.contextGraphId).toBe(CG);
+    expect(lc(error.details.payerAddress)).toBe(lc(payer));
+    expect(error.details.attestedAuthorAddress).toBe(AUTHOR);
+
+    // Facts and text must describe the same rejection — a message rendered from
+    // different values than the object reports would be worse than either alone.
+    expect(error.message).toBe(formatPublisherNotAuthorizedForCgMessage(error.details));
+
+    // Frozen: one error's diagnosis cannot be mutated into disagreeing with its text.
+    expect(Object.isFrozen(error.details)).toBe(true);
+  });
+
+  it('carries the pool facts on a signer-pool rejection, author consulted and refused', async () => {
+    const { a, pool } = makeAdapter([], ATTESTED_AUTHOR_PUBLISH_AUTHZ_MIN_KAL_VERSION, {
+      extraKeys: [PK_B],
+    });
+
+    const error = await caught(() => a._authorizedPublisherSigners(pool, CG, AUTHOR));
+
+    // Author WAS weighed here (supported lifecycle) and refused — the opposite
+    // diagnosis to the version-gated case above, distinguishable without parsing.
+    expect(error.details.attestedAuthorConsidered).toBe(true);
+    expect(error.details.deployedLifecycleVersion)
+      .toBe(ATTESTED_AUTHOR_PUBLISH_AUTHZ_MIN_KAL_VERSION);
+    expect(error.details.payerPoolAddresses).toEqual(pool.map((w) => w.address));
+    expect(error.message).toBe(formatPublisherNotAuthorizedForCgMessage(error.details));
+  });
 });
 
 describe('#1689 publish admission — fails closed on EVERY path [CH-1689-F]', () => {
@@ -251,6 +295,66 @@ describe('#1689 publish admission — one condition, one error contract [CH-1689
   });
 });
 
+describe('#1689 publish admission — author-aware NO_FUNDED enrichment [CH-1689-E]', () => {
+  // `enrichInsufficientPublisherFundsError` decides whether a funding failure is the
+  // TERMINAL `NO_FUNDED_PUBLISHER_WALLET` ("no wallet is a viable reroute") or a
+  // recoverable wrong-pick. It answers that with `poolHasFundableSigner`, which must
+  // be asked on the SAME two-principal rule the publish is held to: an attested
+  // author the CG authorizes makes every funded wallet admissible.
+  //
+  // Nothing else guards the author argument at that call site. Drop it and the
+  // payer-only NO_FUNDED tests still pass, while a recoverable reroute is
+  // misreported as terminal — a misclassification in the same family as the bug
+  // this PR fixes. Mutation-proven: removing the argument fails exactly this test.
+  it('an authorized author keeps a fundable pool wallet a viable reroute (NOT terminal NO_FUNDED)', async () => {
+    const { a, pool } = makeAdapter(
+      // ONLY the attested author is authorized — no wallet in the pool is.
+      [AUTHOR.toLowerCase()],
+      ATTESTED_AUTHOR_PUBLISH_AUTHZ_MIN_KAL_VERSION,
+      { extraKeys: [PK_B] },
+    );
+    const [pinned, other] = pool;
+    // The pinned payer is short on TRAC; the other pool wallet can cover the cost.
+    a.getWalletFunding = async (address: string) => (
+      address.toLowerCase() === pinned.address.toLowerCase()
+        ? { native: 10n ** 18n, trac: 0n }
+        : { native: 10n ** 18n, trac: 10n ** 18n }
+    );
+    a.isWalletPublishFundable = async (address: string) =>
+      address.toLowerCase() !== pinned.address.toLowerCase();
+    a.snapshotPublisherWalletBalances = async () => [];
+
+    // A TRAC shortfall surfaces as a funds-shaped transferFrom revert.
+    const original = new Error('ERC20: transfer amount exceeds balance');
+    const enriched = await a.enrichInsufficientPublisherFundsError(
+      original, pinned, CG, 1_000n, AUTHOR,
+    );
+
+    expect(enriched).not.toBeInstanceOf(InsufficientPublisherFundsError);
+    // The original error is preserved so a retry can reroute to the funded wallet.
+    expect(enriched).toBe(original);
+    void other;
+  });
+
+  it('with no author, an unauthorized-and-unfunded pool is still terminal NO_FUNDED (unchanged)', async () => {
+    // The payer-only behaviour this must not disturb: nothing admissible is
+    // fundable, so the whole-pool diagnosis is correct and stays terminal.
+    const { a, pool } = makeAdapter([], ATTESTED_AUTHOR_PUBLISH_AUTHZ_MIN_KAL_VERSION, {
+      extraKeys: [PK_B],
+    });
+    const [pinned] = pool;
+    a.getWalletFunding = async () => ({ native: 10n ** 18n, trac: 0n });
+    a.isWalletPublishFundable = async () => false;
+    a.snapshotPublisherWalletBalances = async () => [];
+
+    const enriched = await a.enrichInsufficientPublisherFundsError(
+      new Error('ERC20: transfer amount exceeds balance'), pinned, CG, 1_000n,
+    );
+
+    expect(enriched).toBeInstanceOf(InsufficientPublisherFundsError);
+  });
+});
+
 describe('#1689 publish admission — cross-package version coupling [CH-1689-V]', () => {
   // The client threshold and `KnowledgeAssetsLifecycle._VERSION` are two literals in
   // two packages maintained by different people. A mismatch fails NOTHING: the