macp-sdk-typescript 0.11.0 → 0.13.0

package/dist/projections/base.js

@@ -1,13 +1,63 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BaseProjection = void 0;
+exports.BaseProjection = exports.PROJECTION_ANOMALY_FIELD_ORDER = exports.ANOMALY_SETTLED_HANDOFF = exports.ANOMALY_DUPLICATE_TASK_ACCEPT = exports.ANOMALY_DUPLICATE_BALLOT = exports.ANOMALY_DUPLICATE_VOTE = void 0;
 const logging_1 = require("../logging");
+/**
+ * The four `ProjectionAnomalyKind` values as named constants — all four are
+ * cross-SDK contract, literally pinned by the spec repo's
+ * `schemas/parity/contract.json` (`projection_anomaly.kinds`, `contract_version`
+ * 1.2.0 — `ANOMALY_DUPLICATE_TASK_ACCEPT`/`ANOMALY_SETTLED_HANDOFF` landed there
+ * under issue #126/#128, after this SDK's PR #134 completed the agreement
+ * `macp-sdk-python`'s PR #95 started). `satisfies` links each constant to the
+ * union above at compile time, so a drifted value fails `npm run check` before
+ * it can ever reach `make verify-parity`.
+ */
+exports.ANOMALY_DUPLICATE_VOTE = 'duplicate_vote';
+exports.ANOMALY_DUPLICATE_BALLOT = 'duplicate_ballot';
+exports.ANOMALY_DUPLICATE_TASK_ACCEPT = 'duplicate_task_accept';
+exports.ANOMALY_SETTLED_HANDOFF = 'settled_handoff';
+/**
+ * Runtime field order for `ProjectionAnomaly`, with the same frozen-set
+ * guarantee as `_ProjectionAnomalyFieldSetIsFrozen` above, expressed as a
+ * value rather than only a type. The spec repo's
+ * `schemas/parity/contract.json` (`projection_anomaly.fields`) pins this
+ * field order as a runtime JSON array, so this SDK needs its own runtime
+ * array to assert against it (see `tests/parity/contract.test.ts`).
+ *
+ * **Public, not hidden — corrected during Phase 2's own verification round.**
+ * An earlier revision of this docblock claimed this constant was
+ * "deliberately NOT added to the public barrel," on the (wrong) assumption
+ * that it would follow `canonicalizeCommitmentPayload`'s precedent in
+ * `commitment-hash.ts`. That precedent doesn't transfer: `commitment-hash.ts`
+ * is barrel-exported via a *named* line in `src/index.ts`
+ * (`export { commitmentHash, isCanonicalCommitmentHash } from
+ * './commitment-hash'`), which can omit a name on purpose. This module is
+ * barrel-exported via `src/projections.ts`'s `export * from
+ * './projections/base'` → `src/index.ts`'s `export * from './projections'`
+ * — a wildcard re-export chain has no way to omit one name, so this constant
+ * reaches `dist/index.d.ts` and the runtime `require('macp-sdk-typescript')`
+ * surface regardless of intent (verified: `node -e "require('./dist/index.js')
+ * .PROJECTION_ANOMALY_FIELD_ORDER"` prints the array). This is harmless —
+ * a small readonly string tuple is no more a surface-area risk than
+ * `STANDARD_MODES` — so the fix is documenting reality, not restructuring
+ * the export chain to force exclusion. Phase 3's public-API snapshot
+ * correctly captures this symbol as part of today's real surface.
+ */
+exports.PROJECTION_ANOMALY_FIELD_ORDER = [
+    'kind',
+    'mode',
+    'messageType',
+    'messageId',
+    'sender',
+    'subjectId',
+    'detail',
+];
 /**
  * Abstract base for in-process mode-state tracking — parity with python-sdk's
  * `macp_sdk.base_projection.BaseProjection`. Maintains a shared transcript,
  * phase string, and commitment payload; subclasses override `applyMode`
- * to handle mode-specific envelopes. `SessionStart` and `Commitment` are
- * handled here so custom modes get the common lifecycle for free.
+ * to handle mode-specific envelopes. `Commitment` is handled here so custom
+ * modes get the common lifecycle for free.
  */
 class BaseProjection {
     /**
@@ -38,18 +88,27 @@ class BaseProjection {
     /**
      * Cardinality anomalies recorded while replaying this projection's
      * accepted transcript (e.g. a duplicate vote or ballot from the same
-     * sender). See `ProjectionAnomaly`. Empty unless a subclass calls
-     * `recordAnomaly`. NOTE: as of this SDK's built-in modes, nothing calls
-     * `recordAnomaly` — `DecisionProjection` and `QuorumProjection` do not
-     * extend `BaseProjection` (see the class docblock) and inline their own
-     * two lines instead. This field and `recordAnomaly` exist for ext-mode
-     * `BaseProjection` subclasses outside this repo.
+     * sender, a duplicate `TaskAccept` competing for an already-held assignee
+     * slot, or a `HandoffAccept`/`HandoffDecline` for an already-settled
+     * handoff). See `ProjectionAnomaly`. Empty unless a subclass calls
+     * `recordAnomaly`. **Corrected 2026-09-25** (this note previously said
+     * nothing calls `recordAnomaly` because `DecisionProjection`/
+     * `QuorumProjection` didn't extend `BaseProjection` — that was true before
+     * issue #91's refactor, and is stale now): both `DecisionProjection`
+     * (`decision.ts`) and `QuorumProjection` (`quorum.ts`) extend
+     * `BaseProjection` today and DO call the inherited `recordAnomaly` when
+     * they discard a duplicate vote/ballot — they just pass a literal
+     * `'duplicate_vote'`/`'duplicate_ballot'` string for `kind` rather than
+     * this file's `ANOMALY_DUPLICATE_VOTE`/`ANOMALY_DUPLICATE_BALLOT`
+     * constants (referencing those constants instead is optional cleanup, not
+     * required by anything in this repo). This field and `recordAnomaly` are
+     * no longer ext-mode-only — any subclass, built-in or ext-mode, uses them.
      */
     anomalies = [];
     /**
      * True once at least one `ProjectionAnomaly` has been recorded — i.e. this
-     * projection observed and discarded a duplicate vote or ballot from the
-     * same sender (see `anomalies` above). This getter is exactly
+     * projection observed and discarded a cardinality anomaly (see `anomalies`
+     * above for the full set of kinds). This getter is exactly
      * `anomalies.length > 0`; it never asserts "this transcript violates the
      * spec" (see `ProjectionAnomaly`'s docblock, and `applyEnvelope`'s "Input
      * contract: accepted-only" section above, for why a projection cannot make
@@ -157,7 +216,19 @@ class BaseProjection {
             this.applyMode(envelope, protoRegistry);
         }
         catch (err) {
-            this.transcript.pop();
+            // Identity (`===`), not deep equality: guards against popping an
+            // unrelated entry if a subclass's `applyMode` pushed something onto
+            // `transcript` itself before throwing (issue #106.4) — two distinct
+            // envelopes can be structurally equal, but only the one this call
+            // itself pushed should ever be popped here. No current subclass does
+            // this (nothing pushes before the fallible decode above), so this
+            // guard is latent, but `BaseProjection` is documented subclassable
+            // API and the failure mode it prevents is worse than the bug the
+            // rollback itself fixes. The dedup-set delete below needs no such
+            // guard — `seenIdAdded` already keys it to this envelope's own id —
+            // and must still run even when the pop is skipped.
+            if (this.transcript.at(-1) === envelope)
+                this.transcript.pop();
             if (seenIdAdded)
                 this.seenMessageIds.delete(envelope.messageId);
             throw err;

package/dist/projections/decision.js

@@ -37,6 +37,23 @@ class DecisionProjection extends base_1.BaseProjection {
             }
             case 'Vote': {
                 const record = payload;
+                // RFC-MACP-0007 §5 rule 2: "Evaluation, Objection, and Vote MUST
+                // reference an existing proposal_id." A conforming runtime never
+                // admits a Vote for an unknown proposal_id into accepted history, but
+                // per the accepted-only input contract (`BaseProjection.applyEnvelope`)
+                // this guards the same class of unfiltered-transcript input that
+                // `HandoffAccept`/`HandoffDecline` already guard against (issue #119,
+                // mirrors issue #111's task.ts fix). Evaluation/Objection need no
+                // matching guard: they only append to audit arrays (see
+                // `docs/api/projections.md` "List accumulators and logical
+                // duplicates"), so an unknown-proposalId record there fabricates no
+                // Map state and moves no phase. Vote is different: without this
+                // guard, `this.votes.get(...) ?? new Map()` below would fabricate a
+                // new `votes` entry for an unknown proposalId, inflating
+                // `voteTotals()`/`majorityWinner()`'s denominators even though no
+                // known proposal exists.
+                if (!this.proposals.has(record.proposalId))
+                    break;
                 const bySender = this.votes.get(record.proposalId) ?? new Map();
                 const kept = bySender.get(envelope.sender);
                 if (kept !== undefined) {
@@ -68,9 +85,12 @@ class DecisionProjection extends base_1.BaseProjection {
                 // not a normative MACP term (it appears once, in passing, at
                 // RFC-MACP-0012 `:211`); this guard is justified by session
                 // terminality, not by a phase specification. An anomaly would be
-                // recorded here too, but `ProjectionAnomalyKind` (`base.ts:8-9`) is
-                // deliberately frozen pending cross-SDK agreement with
-                // macp-sdk-python.
+                // recorded here too, but unlike five of the six sites that were
+                // "frozen pending cross-SDK agreement" (issue #126/#128, now
+                // resolved for `duplicate_task_accept`/`settled_handoff` — see
+                // `base.ts`), this one is a session-terminality phase-regression
+                // guard, not a settlement discard, and remains genuinely undecided
+                // per #128's own explicit scoping. No behavior change here.
                 if (this.phase !== 'Committed') {
                     this.phase = 'Voting';
                 }

package/dist/projections/handoff.js

@@ -27,6 +27,11 @@ class HandoffProjection extends base_1.BaseProjection {
             case 'HandoffContext': {
                 const record = payload;
                 const handoff = this.handoffs.get(record.handoffId);
+                // RFC-MACP-0010 §5 rule 2: HandoffContext MUST reference an existing
+                // handoff_id, so the phase transition belongs inside this guard too
+                // (issue #119, same shape as issue #111) — a HandoffContext for an
+                // unknown handoff_id must not advance `phase` past `'OfferPending'`
+                // while a different, real handoff is still pending.
                 if (handoff) {
                     // Per RFC-MACP-0010 §2.1: context after accept is permitted as supplementary docs.
                     // Only update status if not already accepted/declined.
@@ -34,9 +39,9 @@ class HandoffProjection extends base_1.BaseProjection {
                         handoff.status = 'context_sent';
                     }
                     handoff.contextContentType = record.contentType;
+                    if (this.phase === 'OfferPending')
+                        this.phase = 'ContextSharing';
                 }
-                if (this.phase === 'OfferPending')
-                    this.phase = 'ContextSharing';
                 break;
             }
             case 'HandoffAccept': {
@@ -47,9 +52,10 @@ class HandoffProjection extends base_1.BaseProjection {
                     // and HandoffDecline MUST reference an existing handoff_id." An
                     // accept for an unknown/never-offered handoff_id is invalid input
                     // (e.g. an unfiltered transcript) and MUST NOT mutate `phase` or
-                    // fabricate a handoff record. An anomaly would be recorded here,
-                    // but `ProjectionAnomalyKind` (`base.ts:8-9`) is deliberately
-                    // frozen pending cross-SDK agreement with macp-sdk-python.
+                    // fabricate a handoff record. Confirmed (issue #126/#128): no
+                    // anomaly is recorded for this case — an unknown `handoff_id` is
+                    // not caller misuse (a projection that joined mid-session may never
+                    // have observed the original offer).
                     break;
                 }
                 // RFC-MACP-0010 §5 rule 4 (`:68`): "Once an offer has been
@@ -58,10 +64,7 @@ class HandoffProjection extends base_1.BaseProjection {
                 // direction too: a `handoff_id` transitions
                 // offered -> accepted | declined exactly once. Only settle if this
                 // handoff hasn't already resolved — the same shape as the
-                // HandoffContext guard just above. An anomaly would be recorded when
-                // this guard discards a competing accept, but `ProjectionAnomalyKind`
-                // (`base.ts:8-9`) is deliberately frozen pending cross-SDK agreement
-                // with macp-sdk-python.
+                // HandoffContext guard just above.
                 if (handoff.status === 'offered' || handoff.status === 'context_sent') {
                     handoff.status = 'accepted';
                     handoff.acceptedBy = record.acceptedBy;
@@ -71,6 +74,17 @@ class HandoffProjection extends base_1.BaseProjection {
                     handoff.implicit = record.implicit ?? false;
                     this.phase = 'Accepted';
                 }
+                else {
+                    this.recordAnomaly({
+                        kind: 'settled_handoff',
+                        mode: envelope.mode,
+                        messageType: envelope.messageType,
+                        messageId: envelope.messageId,
+                        sender: envelope.sender,
+                        subjectId: record.handoffId,
+                        detail: `sender ${envelope.sender} attempted HandoffAccept for ${record.handoffId}, but it already settled as '${handoff.status}'`,
+                    });
+                }
                 break;
             }
             case 'HandoffDecline': {
@@ -81,22 +95,31 @@ class HandoffProjection extends base_1.BaseProjection {
                     // and HandoffDecline MUST reference an existing handoff_id." A
                     // decline for an unknown/never-offered handoff_id is invalid input
                     // (e.g. an unfiltered transcript) and MUST NOT mutate `phase` or
-                    // fabricate a handoff record. An anomaly would be recorded here,
-                    // but `ProjectionAnomalyKind` (`base.ts:8-9`) is deliberately
-                    // frozen pending cross-SDK agreement with macp-sdk-python.
+                    // fabricate a handoff record. Confirmed (issue #126/#128): no
+                    // anomaly is recorded for this case — an unknown `handoff_id` is
+                    // not caller misuse (a projection that joined mid-session may never
+                    // have observed the original offer).
                     break;
                 }
                 // RFC-MACP-0010 §5 rule 4 (`:68`) + §5.1(4) (`:113-116`): a
                 // `handoff_id` settles once. A decline after the handoff already
-                // settled (accepted or declined) is invalid and ignored. An anomaly
-                // would be recorded here too, but `ProjectionAnomalyKind`
-                // (`base.ts:8-9`) is deliberately frozen pending cross-SDK agreement
-                // with macp-sdk-python.
+                // settled (accepted or declined) is invalid and ignored.
                 if (handoff.status === 'offered' || handoff.status === 'context_sent') {
                     handoff.status = 'declined';
                     handoff.declinedBy = record.declinedBy;
                     this.phase = 'Declined';
                 }
+                else {
+                    this.recordAnomaly({
+                        kind: 'settled_handoff',
+                        mode: envelope.mode,
+                        messageType: envelope.messageType,
+                        messageId: envelope.messageId,
+                        sender: envelope.sender,
+                        subjectId: record.handoffId,
+                        detail: `sender ${envelope.sender} attempted HandoffDecline for ${record.handoffId}, but it already settled as '${handoff.status}'`,
+                    });
+                }
                 break;
             }
             default:

package/dist/projections/proposal.js

@@ -69,11 +69,25 @@ class ProposalProjection extends base_1.BaseProjection {
                     reason: record.reason,
                     sender: envelope.sender,
                 });
+                // RFC-MACP-0008 §5 rule 3 requires `Reject` to reference an existing
+                // proposal_id, so `this.phase` must only move to the terminal state
+                // when a proposal record for it actually exists here (issue #119,
+                // same shape as issue #111's TaskComplete/TaskFail fix) — otherwise
+                // an unfiltered transcript could flip `phase` to `'TerminalRejected'`
+                // (a TERMINAL_PHASES member, see `src/agent/participant.ts`) on a
+                // never-seen proposalId, ending a live Participant's run() loop for a
+                // session that never actually terminated. `this.rejections.push(...)`
+                // above stays unconditional — it's an append-only audit log (see
+                // `docs/api/projections.md` "List accumulators and logical
+                // duplicates"), so `isTerminallyRejected`/`hasTerminalRejection` can
+                // still report `true` for an unknown id even though `phase` does not
+                // move; that split is intentional, not a residual bug.
                 if (terminal) {
                     const proposal = this.proposals.get(record.proposalId);
-                    if (proposal)
+                    if (proposal) {
                         proposal.status = 'rejected';
-                    this.phase = 'TerminalRejected';
+                        this.phase = 'TerminalRejected';
+                    }
                 }
                 break;
             }

package/dist/projections/quorum.js

@@ -38,6 +38,19 @@ class QuorumProjection extends base_1.BaseProjection {
         }
     }
     setBallot(envelope, requestId, vote, reason) {
+        // RFC-MACP-0011 §5 rule 3 (`rfcs/RFC-MACP-0011-quorum-mode.md:69`): a ballot
+        // MUST reference the Session's accepted request_id. `applyEnvelope`'s input
+        // contract is accepted-only (see accepted-only-contract.test.ts), not a
+        // guarantee every field inside an accepted envelope is itself valid, so an
+        // unfiltered/multi-session transcript could still carry a ballot for a
+        // request_id this projection never saw an ApprovalRequest for. Without this
+        // guard that would fabricate a `ballots` Map entry: votedSenders() and
+        // approvalCount()/rejectionCount()/abstentionCount() would report on a
+        // request that doesn't exist, and a second such ballot from the same sender
+        // would fire a spurious duplicate_ballot anomaly against it (issue #121,
+        // same bug shape as issue #119's proposal.ts/handoff.ts/decision.ts sites).
+        if (!this.requests.has(requestId))
+            return;
         const senderMap = this.ballots.get(requestId) ?? new Map();
         const kept = senderMap.get(envelope.sender);
         if (kept !== undefined) {

package/dist/projections/task.d.ts

@@ -19,13 +19,13 @@ export interface TaskUpdateRecord {
     message?: string;
     sender: string;
 }
-export interface TaskCompletionRecord {
+export interface TaskCompleteRecord {
     taskId: string;
     assignee: string;
     summary?: string;
     sender: string;
 }
-export interface TaskFailureRecord {
+export interface TaskFailRecord {
     taskId: string;
     assignee: string;
     errorCode?: string;
@@ -37,8 +37,8 @@ export declare class TaskProjection extends BaseProjection {
     protected readonly mode = "macp.mode.task.v1";
     readonly tasks: Map<string, TaskRecord>;
     readonly updates: TaskUpdateRecord[];
-    readonly completions: TaskCompletionRecord[];
-    readonly failures: TaskFailureRecord[];
+    readonly completions: TaskCompleteRecord[];
+    readonly failures: TaskFailRecord[];
     phase: 'Pending' | 'Requested' | 'InProgress' | 'Completed' | 'Failed' | 'Committed';
     /**
      * The **session-level** active assignment: who currently holds the session's
@@ -63,7 +63,7 @@ export declare class TaskProjection extends BaseProjection {
     /** Handle a Task-mode envelope. See `BaseProjection.applyEnvelope` for the accepted-only input contract and redelivery/rollback semantics shared by all built-in modes. */
     protected applyMode(envelope: Envelope, protoRegistry: ProtoRegistry): void;
     getTask(taskId: string): TaskRecord | undefined;
-    isComplete(taskId: string): boolean;
+    isCompleted(taskId: string): boolean;
     isFailed(taskId: string): boolean;
     isRetryable(taskId: string): boolean;
     progressOf(taskId: string): number;

package/dist/projections/task.js

@@ -74,16 +74,37 @@ class TaskProjection extends base_1.BaseProjection {
                 // below, which frees the slot — see its comment for why that needs no
                 // policy input.
                 //
-                // An anomaly would be recorded when this guard discards a second
-                // `TaskAccept`, but `ProjectionAnomalyKind` (`base.ts:8-9`) is
-                // deliberately frozen pending cross-SDK agreement with
-                // macp-sdk-python.
-                if (task && this.activeAssignment === undefined) {
-                    task.assignee = record.assignee;
-                    task.status = 'accepted';
-                    this.activeAssignment = { sender: envelope.sender, taskId: record.taskId };
-                    this.phase = 'InProgress';
+                // A discarded second `TaskAccept` records a `duplicate_task_accept`
+                // anomaly (issue #126/#128) only when this projection actually has a
+                // `TaskRequest` on file for the losing `taskId` (`task` is defined) —
+                // an accept for a `taskId` this projection never saw a `TaskRequest`
+                // for stays a silent no-op below, since a projection that joined
+                // mid-session may never have observed the original request, and that
+                // is not caller misuse. Note this guard's `activeAssignment` slot is
+                // session-scoped (see the comment above), so the `taskId` that loses
+                // here need not be the same one the slot is already held for — it is
+                // simply a second, separately-requested task competing for the one
+                // slot the session allows.
+                if (task) {
+                    if (this.activeAssignment === undefined) {
+                        task.assignee = record.assignee;
+                        task.status = 'accepted';
+                        this.activeAssignment = { sender: envelope.sender, taskId: record.taskId };
+                        this.phase = 'InProgress';
+                    }
+                    else {
+                        this.recordAnomaly({
+                            kind: 'duplicate_task_accept',
+                            mode: envelope.mode,
+                            messageType: envelope.messageType,
+                            messageId: envelope.messageId,
+                            sender: envelope.sender,
+                            subjectId: record.taskId,
+                            detail: `sender ${envelope.sender} attempted TaskAccept for ${record.taskId}, but ${this.activeAssignment.sender} already holds the session's one assignee slot with task ${this.activeAssignment.taskId}`,
+                        });
+                    }
                 }
+                // unknown taskId (task undefined): stays a silent no-op.
                 break;
             }
             case 'TaskReject': {
@@ -137,17 +158,18 @@ class TaskProjection extends base_1.BaseProjection {
                 if (task) {
                     task.status = 'completed';
                     task.progress = 1;
+                    this.phase = 'Completed';
                 }
-                this.phase = 'Completed';
                 break;
             }
             case 'TaskFail': {
                 const record = payload;
                 this.failures.push({ ...record, retryable: record.retryable ?? false, sender: envelope.sender });
                 const task = this.tasks.get(record.taskId);
-                if (task)
+                if (task) {
                     task.status = 'failed';
-                this.phase = 'Failed';
+                    this.phase = 'Failed';
+                }
                 break;
             }
             default:
@@ -157,7 +179,7 @@ class TaskProjection extends base_1.BaseProjection {
     getTask(taskId) {
         return this.tasks.get(taskId);
     }
-    isComplete(taskId) {
+    isCompleted(taskId) {
         return this.tasks.get(taskId)?.status === 'completed';
     }
     isFailed(taskId) {

package/dist/proposal.d.ts

@@ -32,6 +32,7 @@ export declare class ProposalSession {
         }[];
         maxSuspendMs?: number;
         sender?: string;
+        auth?: AuthConfig;
     }): Promise<Ack>;
     propose(input: ProposalModeProposalPayload & {
         sender?: string;

package/dist/proposal.js

@@ -60,10 +60,10 @@ class ProposalSession {
             mode: constants_1.MODE_PROPOSAL,
             messageType: 'SessionStart',
             sessionId: this.sessionId,
-            sender: this.senderFor(input.sender),
+            sender: this.senderFor(input.sender, input.auth),
             payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_PROPOSAL, 'SessionStart', (0, envelope_1.toProtoPayload)(payload)),
         });
-        return this.sendAndTrack(envelope, this.auth);
+        return this.sendAndTrack(envelope, input.auth ?? this.auth);
     }
     async propose(input) {
         (0, validation_1.validateRequiredField)('proposalId', input.proposalId);

package/dist/proto-registry.d.ts

@@ -11,7 +11,13 @@ export declare class ProtoRegistry {
      * Decode an `ext.multi_round.v1` `Contribute` payload, accepting both wire
      * formats: legacy JSON (`{"value":"..."}`, still replayed verbatim from
      * pre-proto histories) and canonical protobuf (`ContributePayload`). Both
-     * normalize to `{ value: string }`.
+     * normalize to `{ value }`, but only the protobuf path's `value` is always
+     * a `string` — the legacy-JSON path passes `parsed.value` through exactly
+     * as `JSON.parse` produced it (issue #124: no `String(...)` coercion, no
+     * `?? ''` fallback for an absent key), so `value` may be `undefined`,
+     * `null`, a number, a boolean, or an object/array for malformed-but-valid
+     * legacy JSON. This method's own contract is observational, not a gate —
+     * see the `contribute_acceptance` note below.
      *
      * Parse-then-fallback (issue #93), not a first-byte shortcut: JSON is always
      * attempted first, and only a `JSON.parse` failure falls through to
@@ -19,8 +25,27 @@ export declare class ProtoRegistry {
      * not generalize — e.g. legacy JSON with leading whitespace has neither byte
      * first, and used to reach `decodeMessage` and throw. Parity with
      * `macp-sdk-python`'s `_decode_json_first_then_proto`, which has always
-     * worked this way. Safe because a canonical proto payload's bytes are
-     * essentially never also syntactically valid JSON.
+     * worked this way.
+     *
+     * **A successful `JSON.parse` is not proof the bytes are legacy JSON**
+     * (issue #104 — this method's prior "essentially never also syntactically
+     * valid JSON" claim was false, not merely imprecise): the canonical proto
+     * tag byte for field 1 (`0x0A`) is itself insignificant JSON whitespace, so
+     * for specific value byte-lengths the length varint — or, when the varint
+     * is itself whitespace, the value's own leading byte — becomes the first
+     * significant character `JSON.parse` sees, and a genuine `ContributePayload`
+     * silently misreads as a JSON number/string/object. Verified directly
+     * (encode-then-decode sweep, value lengths 1-127, seven value shapes): every
+     * one of lengths 9, 10, 13, 32, 34, 45, 48, 49-57, and 123 corrupted before
+     * `isCanonicalProto` below, most to total silent data loss
+     * (`String(undefined ?? '') === ''`), zero corrupt after.
+     *
+     * `isCanonicalProto` resolves the ambiguity by tie-break, not by refusing
+     * to try JSON first: bytes that parse as JSON *and* are the exact canonical
+     * proto encoding are treated as proto. This has a narrow, priced cost on
+     * the reverse direction (legacy JSON misread as proto) that it introduces
+     * rather than merely fails to close — see `isCanonicalProto`'s own
+     * docblock.
      *
      * An empty payload falls through the same path: `JSON.parse('')` throws, so
      * it reaches `decodeMessage` on zero bytes, which yields `{}` (proto3
@@ -31,6 +56,47 @@ export declare class ProtoRegistry {
      * currently `macp-runtime`-only), not something this method decides.
      */
     private decodeMultiRoundContribute;
+    /**
+     * True iff `payload` is the exact canonical protobuf encoding of
+     * `typeName` — used to break the JSON/proto ambiguity in
+     * `decodeMultiRoundContribute` (issue #104): bytes that both parse as JSON
+     * *and* round-trip byte-identically through the proto message are treated
+     * as proto, not JSON.
+     *
+     * `macp-sdk-python`'s equivalent (`_is_canonical_proto`) needs an explicit
+     * `DiscardUnknownFields()` step before comparing, because Python's protobuf
+     * runtime preserves unknown fields verbatim through
+     * `ParseFromString`/`SerializeToString` by default — without it, a plain
+     * round-trip check misclassified several whitespace-prefixed legacy-JSON
+     * payloads as canonical proto. **`protobufjs` needs no equivalent step**:
+     * verified directly (a synthetic payload with a declared field-1 string
+     * plus an undeclared field 2) that `Type.decode()` silently drops fields
+     * not in the schema rather than preserving them, so `Type.encode()` can
+     * never reproduce bytes it never captured — a byte-exact round-trip here
+     * is already proof the payload is *exactly* the single-field encoding, no
+     * unknown fields possible. Confirmed this closes the same
+     * whitespace-prefixed false-positive class `DiscardUnknownFields` closes
+     * in Python (tab/space-prefixed legacy JSON at several lengths).
+     *
+     * One narrow, symmetric residual survives regardless — genuinely
+     * irreducible, not a gap this check merely fails to close: a payload whose
+     * first byte is a literal `0x0A` (`\n`) and whose remainder forms a
+     * complete, well-formed proto field-1 string with nothing left over has no
+     * unknown field for either implementation to expose a mismatch on, because
+     * it *is*, byte for byte, both a legal JSON reading and the canonical
+     * proto encoding of some (possibly nonsensical) string. Verified instances
+     * (this SDK's own `JSON.stringify`, which — unlike Python's `json.dumps`
+     * — omits the space after `:`, shifting the colliding lengths by one byte
+     * from `macp-sdk-python`'s pinned cases): `'\n' + JSON.stringify({value:
+     * 'z'.repeat(112)})`, and with one extra whitespace byte inserted after the
+     * `\n`, `'\r'` at value length 1 and `' '` at value length 20. A real
+     * legacy-JSON sender would need to deliberately prefix with a literal
+     * newline byte for this to matter — this SDK's own JSON producers never
+     * emit one — so the trade (fixing the ordinary, naturally-reachable
+     * forward-direction corruption above at the cost of this adversarial,
+     * unreachable-by-any-known-encoder reverse case) is the right one.
+     */
+    private isCanonicalProto;
     private lookupType;
     private tryDecodeUtf8;
 }