macp-sdk-typescript 0.10.0 → 0.12.0

package/dist/projections/quorum.d.ts

@@ -1,4 +1,4 @@
-import type { ProjectionAnomaly } from './base';
+import { BaseProjection } from './base';
 import type { Envelope } from '../types';
 import type { ProtoRegistry } from '../proto-registry';
 export interface ApprovalRequestRecord {
@@ -14,57 +14,13 @@ export interface BallotRecord {
     reason?: string;
     sender: string;
 }
-export declare class QuorumProjection {
+export declare class QuorumProjection extends BaseProjection {
+    protected readonly mode = "macp.mode.quorum.v1";
     readonly requests: Map<string, ApprovalRequestRecord>;
     readonly ballots: Map<string, Map<string, BallotRecord>>;
-    /**
-     * The session's accepted history, one envelope per unique `message_id`. See
-     * `BaseProjection.transcript` (`src/projections/base.ts`) for the full
-     * redelivery-idempotence contract (RFC-MACP-0006 §3.2); duplicated here
-     * only as a one-line pointer.
-     */
-    readonly transcript: Envelope[];
-    /**
-     * Cardinality anomalies recorded while replaying this projection's accepted
-     * transcript (e.g. a duplicate ballot across `Approve`/`Reject`/`Abstain`
-     * from the same sender for the same `request_id`). See
-     * `BaseProjection.anomalies` (`src/projections/base.ts`) for the canonical
-     * description; duplicated here only as a one-line pointer.
-     */
-    readonly anomalies: ProjectionAnomaly[];
     phase: 'Pending' | 'Voting' | 'Committed';
-    commitment?: Record<string, unknown>;
-    /**
-     * `message_id`s already applied to this projection. See
-     * `BaseProjection.seenMessageIds` (`src/projections/base.ts`) for the full
-     * redelivery-idempotence rationale (RFC-MACP-0006 §3.2); duplicated here
-     * only as a one-line pointer.
-     */
-    private readonly seenMessageIds;
-    /**
-     * Apply one envelope to this projection's in-process state.
-     *
-     * Input contract: **accepted-only**, caller-maintained (`Envelope` carries
-     * no acceptance marker). Canonical source: `schemas/conformance/README.md`
-     * "Notes:", RFC-MACP-0007 §5.3, RFC-MACP-0011 §5. Full rationale and failure
-     * mode are documented once, on `BaseProjection.applyEnvelope`
-     * (`src/projections/base.ts`), and duplicated here only as a one-line
-     * pointer so six independent copies of the same prose cannot drift.
-     *
-     * Redelivery idempotence: a redelivered envelope (same `message_id`) is a
-     * non-event — not appended to `transcript`, not passed to the `switch`.
-     * See `BaseProjection.applyEnvelope` for the full RFC-MACP-0006 §3.2
-     * citation; duplicated here only as a one-line pointer.
-     */
-    applyEnvelope(envelope: Envelope, protoRegistry: ProtoRegistry): void;
-    /**
-     * True once at least one `ProjectionAnomaly` has been recorded. See
-     * `BaseProjection.hasAnomalies` (`src/projections/base.ts`) for the
-     * canonical description; duplicated here only as a one-line pointer.
-     */
-    get hasAnomalies(): boolean;
-    get isCommitted(): boolean;
-    get isPositiveOutcome(): boolean | undefined;
+    /** Handle a Quorum-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;
     private setBallot;
     approvalCount(requestId: string): number;
     rejectionCount(requestId: string): number;

package/dist/projections/quorum.js

@@ -2,64 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QuorumProjection = void 0;
 const constants_1 = require("../constants");
-const logging_1 = require("../logging");
-class QuorumProjection {
+const base_1 = require("./base");
+class QuorumProjection extends base_1.BaseProjection {
+    mode = constants_1.MODE_QUORUM;
     requests = new Map();
     ballots = new Map();
-    /**
-     * The session's accepted history, one envelope per unique `message_id`. See
-     * `BaseProjection.transcript` (`src/projections/base.ts`) for the full
-     * redelivery-idempotence contract (RFC-MACP-0006 §3.2); duplicated here
-     * only as a one-line pointer.
-     */
-    transcript = [];
-    /**
-     * Cardinality anomalies recorded while replaying this projection's accepted
-     * transcript (e.g. a duplicate ballot across `Approve`/`Reject`/`Abstain`
-     * from the same sender for the same `request_id`). See
-     * `BaseProjection.anomalies` (`src/projections/base.ts`) for the canonical
-     * description; duplicated here only as a one-line pointer.
-     */
-    anomalies = [];
     phase = 'Pending';
-    commitment;
-    /**
-     * `message_id`s already applied to this projection. See
-     * `BaseProjection.seenMessageIds` (`src/projections/base.ts`) for the full
-     * redelivery-idempotence rationale (RFC-MACP-0006 §3.2); duplicated here
-     * only as a one-line pointer.
-     */
-    seenMessageIds = new Set();
-    /**
-     * Apply one envelope to this projection's in-process state.
-     *
-     * Input contract: **accepted-only**, caller-maintained (`Envelope` carries
-     * no acceptance marker). Canonical source: `schemas/conformance/README.md`
-     * "Notes:", RFC-MACP-0007 §5.3, RFC-MACP-0011 §5. Full rationale and failure
-     * mode are documented once, on `BaseProjection.applyEnvelope`
-     * (`src/projections/base.ts`), and duplicated here only as a one-line
-     * pointer so six independent copies of the same prose cannot drift.
-     *
-     * Redelivery idempotence: a redelivered envelope (same `message_id`) is a
-     * non-event — not appended to `transcript`, not passed to the `switch`.
-     * See `BaseProjection.applyEnvelope` for the full RFC-MACP-0006 §3.2
-     * citation; duplicated here only as a one-line pointer.
-     */
-    applyEnvelope(envelope, protoRegistry) {
-        if (envelope.mode !== constants_1.MODE_QUORUM)
-            return;
-        if (envelope.messageId) {
-            if (this.seenMessageIds.has(envelope.messageId)) {
-                logging_1.logger.debug('projection redelivery ignored', {
-                    messageId: envelope.messageId,
-                    mode: envelope.mode,
-                    messageType: envelope.messageType,
-                });
-                return;
-            }
-            this.seenMessageIds.add(envelope.messageId);
-        }
-        this.transcript.push(envelope);
+    /** Handle a Quorum-mode envelope. See `BaseProjection.applyEnvelope` for the accepted-only input contract and redelivery/rollback semantics shared by all built-in modes. */
+    applyMode(envelope, protoRegistry) {
         const payload = protoRegistry.decodeKnownPayload(envelope.mode, envelope.messageType, envelope.payload);
         switch (envelope.messageType) {
             case 'ApprovalRequest': {
@@ -83,34 +33,24 @@ class QuorumProjection {
                 this.setBallot(envelope, record.requestId, 'abstain', record.reason);
                 break;
             }
-            case 'Commitment': {
-                this.commitment = payload;
-                this.phase = 'Committed';
-                break;
-            }
             default:
                 break;
         }
     }
-    /**
-     * True once at least one `ProjectionAnomaly` has been recorded. See
-     * `BaseProjection.hasAnomalies` (`src/projections/base.ts`) for the
-     * canonical description; duplicated here only as a one-line pointer.
-     */
-    get hasAnomalies() {
-        return this.anomalies.length > 0;
-    }
-    get isCommitted() {
-        return this.commitment !== undefined;
-    }
-    get isPositiveOutcome() {
-        if (!this.commitment)
-            return undefined;
-        const val = this.commitment.outcomePositive ??
-            this.commitment.outcome_positive;
-        return val !== undefined ? Boolean(val) : true;
-    }
     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) {
@@ -129,7 +69,7 @@ class QuorumProjection {
             // by RFC-0011 either; it is parity with RFC-MACP-0007 §5 item 3's
             // explicit first-stands rule for `Vote`, plus macp-runtime's enforced
             // first-wins behaviour.
-            const anomaly = {
+            this.recordAnomaly({
                 kind: 'duplicate_ballot',
                 mode: envelope.mode,
                 messageType: envelope.messageType,
@@ -137,9 +77,7 @@ class QuorumProjection {
                 sender: envelope.sender,
                 subjectId: requestId,
                 detail: `sender ${envelope.sender} already cast '${kept.vote}' on request ${requestId}; discarded '${vote}'`,
-            };
-            this.anomalies.push(anomaly);
-            logging_1.logger.warn('projection anomaly', anomaly);
+            });
             return;
         }
         senderMap.set(envelope.sender, { requestId, vote, reason, sender: envelope.sender });

package/dist/projections/task.d.ts

@@ -1,4 +1,4 @@
-import type { ProjectionAnomaly } from './base';
+import { BaseProjection } from './base';
 import type { Envelope } from '../types';
 import type { ProtoRegistry } from '../proto-registry';
 export interface TaskRecord {
@@ -19,13 +19,21 @@ export interface TaskUpdateRecord {
     message?: string;
     sender: string;
 }
-export interface TaskCompletionRecord {
+export interface TaskCompleteRecord {
     taskId: string;
     assignee: string;
     summary?: string;
     sender: string;
 }
-export interface TaskFailureRecord {
+/**
+ * @deprecated Use {@link TaskCompleteRecord}. Renamed for cross-SDK naming
+ * parity (multiagentcoordinationprotocol#135, issue #138) — the record now
+ * mirrors its triggering `TaskComplete` message type the way its sibling
+ * {@link TaskUpdateRecord} already mirrors `TaskUpdate`, and matches
+ * `macp-sdk-python`'s `TaskCompleteRecord`. Scheduled for removal in 0.13.0.
+ */
+export type TaskCompletionRecord = TaskCompleteRecord;
+export interface TaskFailRecord {
     taskId: string;
     assignee: string;
     errorCode?: string;
@@ -33,34 +41,21 @@ export interface TaskFailureRecord {
     retryable: boolean;
     sender: string;
 }
-export declare class TaskProjection {
+/**
+ * @deprecated Use {@link TaskFailRecord}. Renamed for cross-SDK naming
+ * parity (multiagentcoordinationprotocol#135, issue #138) — the record now
+ * mirrors its triggering `TaskFail` message type the way its sibling
+ * {@link TaskUpdateRecord} already mirrors `TaskUpdate`, and matches
+ * `macp-sdk-python`'s `TaskFailRecord`. Scheduled for removal in 0.13.0.
+ */
+export type TaskFailureRecord = TaskFailRecord;
+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[];
-    /**
-     * The session's accepted history, one envelope per unique `message_id`. See
-     * `BaseProjection.transcript` (`src/projections/base.ts`) for the full
-     * redelivery-idempotence contract (RFC-MACP-0006 §3.2); duplicated here
-     * only as a one-line pointer.
-     */
-    readonly transcript: Envelope[];
-    /**
-     * Cardinality anomalies recorded while replaying this projection's accepted
-     * transcript. See `BaseProjection.anomalies` (`src/projections/base.ts`)
-     * for the canonical description; duplicated here only as a one-line
-     * pointer. No built-in detection populates this for Task mode.
-     */
-    readonly anomalies: ProjectionAnomaly[];
+    readonly completions: TaskCompleteRecord[];
+    readonly failures: TaskFailRecord[];
     phase: 'Pending' | 'Requested' | 'InProgress' | 'Completed' | 'Failed' | 'Committed';
-    commitment?: Record<string, unknown>;
-    /**
-     * `message_id`s already applied to this projection. See
-     * `BaseProjection.seenMessageIds` (`src/projections/base.ts`) for the full
-     * redelivery-idempotence rationale (RFC-MACP-0006 §3.2); duplicated here
-     * only as a one-line pointer.
-     */
-    private readonly seenMessageIds;
     /**
      * The **session-level** active assignment: who currently holds the session's
      * single assignee slot, and which `task_id` they took it on.
@@ -81,31 +76,16 @@ export declare class TaskProjection {
      * the right `TaskRecord.assignee` even on a multi-task transcript.
      */
     private activeAssignment?;
+    /** 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;
+    isCompleted(taskId: string): boolean;
     /**
-     * Apply one envelope to this projection's in-process state.
-     *
-     * Input contract: **accepted-only**, caller-maintained (`Envelope` carries
-     * no acceptance marker). Canonical source: `schemas/conformance/README.md`
-     * "Notes:", RFC-MACP-0007 §5.3, RFC-MACP-0011 §5. Full rationale and failure
-     * mode are documented once, on `BaseProjection.applyEnvelope`
-     * (`src/projections/base.ts`), and duplicated here only as a one-line
-     * pointer so six independent copies of the same prose cannot drift.
-     *
-     * Redelivery idempotence: a redelivered envelope (same `message_id`) is a
-     * non-event — not appended to `transcript`, not passed to the `switch`.
-     * See `BaseProjection.applyEnvelope` for the full RFC-MACP-0006 §3.2
-     * citation; duplicated here only as a one-line pointer.
-     */
-    applyEnvelope(envelope: Envelope, protoRegistry: ProtoRegistry): void;
-    /**
-     * True once at least one `ProjectionAnomaly` has been recorded. See
-     * `BaseProjection.hasAnomalies` (`src/projections/base.ts`) for the
-     * canonical description; duplicated here only as a one-line pointer.
+     * @deprecated Use {@link isCompleted}. Renamed for cross-SDK naming parity
+     * (multiagentcoordinationprotocol#135, issue #138) — every other `is*`
+     * predicate in this SDK is past-participle, and `macp-sdk-python` has
+     * always spelled this `is_completed`. Scheduled for removal in 0.13.0.
      */
-    get hasAnomalies(): boolean;
-    get isCommitted(): boolean;
-    get isPositiveOutcome(): boolean | undefined;
-    getTask(taskId: string): TaskRecord | undefined;
     isComplete(taskId: string): boolean;
     isFailed(taskId: string): boolean;
     isRetryable(taskId: string): boolean;

package/dist/projections/task.js

@@ -2,35 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TaskProjection = void 0;
 const constants_1 = require("../constants");
-const logging_1 = require("../logging");
-class TaskProjection {
+const base_1 = require("./base");
+class TaskProjection extends base_1.BaseProjection {
+    mode = constants_1.MODE_TASK;
     tasks = new Map();
     updates = [];
     completions = [];
     failures = [];
-    /**
-     * The session's accepted history, one envelope per unique `message_id`. See
-     * `BaseProjection.transcript` (`src/projections/base.ts`) for the full
-     * redelivery-idempotence contract (RFC-MACP-0006 §3.2); duplicated here
-     * only as a one-line pointer.
-     */
-    transcript = [];
-    /**
-     * Cardinality anomalies recorded while replaying this projection's accepted
-     * transcript. See `BaseProjection.anomalies` (`src/projections/base.ts`)
-     * for the canonical description; duplicated here only as a one-line
-     * pointer. No built-in detection populates this for Task mode.
-     */
-    anomalies = [];
     phase = 'Pending';
-    commitment;
-    /**
-     * `message_id`s already applied to this projection. See
-     * `BaseProjection.seenMessageIds` (`src/projections/base.ts`) for the full
-     * redelivery-idempotence rationale (RFC-MACP-0006 §3.2); duplicated here
-     * only as a one-line pointer.
-     */
-    seenMessageIds = new Set();
     /**
      * The **session-level** active assignment: who currently holds the session's
      * single assignee slot, and which `task_id` they took it on.
@@ -51,36 +30,8 @@ class TaskProjection {
      * the right `TaskRecord.assignee` even on a multi-task transcript.
      */
     activeAssignment;
-    /**
-     * Apply one envelope to this projection's in-process state.
-     *
-     * Input contract: **accepted-only**, caller-maintained (`Envelope` carries
-     * no acceptance marker). Canonical source: `schemas/conformance/README.md`
-     * "Notes:", RFC-MACP-0007 §5.3, RFC-MACP-0011 §5. Full rationale and failure
-     * mode are documented once, on `BaseProjection.applyEnvelope`
-     * (`src/projections/base.ts`), and duplicated here only as a one-line
-     * pointer so six independent copies of the same prose cannot drift.
-     *
-     * Redelivery idempotence: a redelivered envelope (same `message_id`) is a
-     * non-event — not appended to `transcript`, not passed to the `switch`.
-     * See `BaseProjection.applyEnvelope` for the full RFC-MACP-0006 §3.2
-     * citation; duplicated here only as a one-line pointer.
-     */
-    applyEnvelope(envelope, protoRegistry) {
-        if (envelope.mode !== constants_1.MODE_TASK)
-            return;
-        if (envelope.messageId) {
-            if (this.seenMessageIds.has(envelope.messageId)) {
-                logging_1.logger.debug('projection redelivery ignored', {
-                    messageId: envelope.messageId,
-                    mode: envelope.mode,
-                    messageType: envelope.messageType,
-                });
-                return;
-            }
-            this.seenMessageIds.add(envelope.messageId);
-        }
-        this.transcript.push(envelope);
+    /** Handle a Task-mode envelope. See `BaseProjection.applyEnvelope` for the accepted-only input contract and redelivery/rollback semantics shared by all built-in modes. */
+    applyMode(envelope, protoRegistry) {
         const payload = protoRegistry.decodeKnownPayload(envelope.mode, envelope.messageType, envelope.payload);
         switch (envelope.messageType) {
             case 'TaskRequest': {
@@ -123,16 +74,37 @@ class TaskProjection {
                 // 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': {
@@ -186,52 +158,39 @@ class TaskProjection {
                 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';
-                break;
-            }
-            case 'Commitment': {
-                this.commitment = payload;
-                this.phase = 'Committed';
+                    this.phase = 'Failed';
+                }
                 break;
             }
             default:
                 break;
         }
     }
-    /**
-     * True once at least one `ProjectionAnomaly` has been recorded. See
-     * `BaseProjection.hasAnomalies` (`src/projections/base.ts`) for the
-     * canonical description; duplicated here only as a one-line pointer.
-     */
-    get hasAnomalies() {
-        return this.anomalies.length > 0;
-    }
-    get isCommitted() {
-        return this.commitment !== undefined;
-    }
-    get isPositiveOutcome() {
-        if (!this.commitment)
-            return undefined;
-        const val = this.commitment.outcomePositive ??
-            this.commitment.outcome_positive;
-        return val !== undefined ? Boolean(val) : true;
-    }
     getTask(taskId) {
         return this.tasks.get(taskId);
     }
-    isComplete(taskId) {
+    isCompleted(taskId) {
         return this.tasks.get(taskId)?.status === 'completed';
     }
+    /**
+     * @deprecated Use {@link isCompleted}. Renamed for cross-SDK naming parity
+     * (multiagentcoordinationprotocol#135, issue #138) — every other `is*`
+     * predicate in this SDK is past-participle, and `macp-sdk-python` has
+     * always spelled this `is_completed`. Scheduled for removal in 0.13.0.
+     */
+    isComplete(taskId) {
+        return this.isCompleted(taskId);
+    }
     isFailed(taskId) {
         return this.tasks.get(taskId)?.status === 'failed';
     }

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

@@ -10,13 +10,93 @@ 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`). JSON is
-     * tried first — mirroring the runtime's permanent decode order — and the two
-     * encodings are disjoint on their first byte (`{` = 0x7b vs proto field-1
-     * tag 0x0A), so a canonical proto payload never mis-parses as JSON and vice
-     * versa. Both normalize to `{ value: string }`.
+     * pre-proto histories) and canonical protobuf (`ContributePayload`). Both
+     * 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
+     * protobuf. A first-byte check (`{` = 0x7b vs proto field-1 tag 0x0A) does
+     * 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.
+     *
+     * **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
+     * defaults) rather than a decode error. This SDK's decode layer is
+     * observational, not an acceptance gate — whether an empty `Contribute`
+     * should be rejected is a runtime-acceptance question (tracked cross-repo,
+     * `contribute_acceptance.empty_payload` in `schemas/parity/contract.json`,
+     * 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;
 }