macp-sdk-typescript 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `macp-sdk-typescript` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 project uses [Semantic Versioning](https://semver.org/).
 
+## [0.8.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.7.1...v0.8.0) (2026-08-31)
+
+
+### ⚠ BREAKING CHANGES
+
+* **projections:** DecisionProjection and QuorumProjection now keep the FIRST accepted Vote/ballot per sender (per proposal_id / request_id) and discard later ones, where they previously kept the last. For a transcript containing a genuine duplicate, derived state changes — most consequentially QuorumProjection.hasQuorum(), which could previously be fabricated by a single sender voting twice under requiredApprovals: 1. Conforming transcripts are unaffected. The discarded message is recorded on the new `anomalies` surface.
+
+### Features
+
+* **projections:** the first accepted vote or ballot stands ([#61](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/61)) ([ac407c3](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/ac407c3767e785b2a1cf82e1ae735a9ebf1138be))
+
+## [0.7.1](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.7.0...v0.7.1) (2026-08-31)
+
+
+### Bug Fixes
+
+* validate explicit empty-string sessionId, and freeze the commitment field set ([#52](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/52)) ([5e4dc25](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/5e4dc25389d948570afbd9653cfd52bc12e97150)), closes [#47](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/47) [#48](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/48)
+
 ## [0.7.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.6.0...v0.7.0) (2026-08-30)
 
 

package/dist/agent/transports.js

@@ -88,6 +88,15 @@ class HttpTransportAdapter {
                         if (itemSeq > this.lastSeq) {
                             this.lastSeq = itemSeq;
                         }
+                        // Normalize message_id -> messageId before yielding: without
+                        // this, `raw` is the raw snake_case JSON straight off the wire,
+                        // so `raw.messageId` is `undefined` and the projection's
+                        // redelivery guard (`if (envelope.messageId)`,
+                        // `src/projections/base.ts`) short-circuits — every polled
+                        // envelope looks id-less and skips dedup entirely, leaving HTTP
+                        // polling silently unprotected against RFC-MACP-0006 §3.2
+                        // redelivery.
+                        const messageId = item.message_id ?? item.messageId ?? '';
                         yield {
                             messageType: item.message_type ?? item.messageType ?? '',
                             sender: item.sender ?? '',
@@ -95,7 +104,7 @@ class HttpTransportAdapter {
                                 ? item.payload
                                 : this.tryParsePayload(item.payload),
                             proposalId: item.proposal_id ?? item.proposalId,
-                            raw: item,
+                            raw: { ...item, messageId },
                             seq: this.seq++,
                         };
                     }

package/dist/agent/types.d.ts

@@ -1,3 +1,4 @@
+import type { ProjectionAnomaly } from '../projections/base';
 import type { Envelope } from '../types';
 export interface IncomingMessage {
     messageType: string;
@@ -62,6 +63,17 @@ export interface ParticipantLike {
 export interface ProjectionLike {
     readonly phase: string;
     readonly transcript: Envelope[];
+    /**
+     * Cardinality anomalies observed and discarded by the projection, in transcript order.
+     *
+     * OPTIONAL, and it must STAY optional. `ProjectionLike` is structurally
+     * implementable by consumers — test fakes, custom transports, alternative
+     * projection implementations — none of which this SDK controls. Making this
+     * member required would break every such implementer at compile time for a
+     * field most of them have no reason to provide. The guard below turns a
+     * later "tightening" into a build failure rather than a silent break.
+     */
+    readonly anomalies?: readonly ProjectionAnomaly[];
 }
 export type MessageHandler = (event: IncomingMessage, ctx: HandlerContext) => void | Promise<void>;
 export type TerminalHandler = (result: TerminalResult) => void | Promise<void>;

package/dist/base-session.js

@@ -26,7 +26,7 @@ class BaseSession {
     projection;
     constructor(client, options = {}) {
         this.client = client;
-        if (options.sessionId)
+        if (options.sessionId !== undefined)
             (0, validation_1.validateSessionId)(options.sessionId);
         this.sessionId = options.sessionId ?? (0, envelope_1.newSessionId)();
         this.modeVersion = options.modeVersion ?? constants_1.DEFAULT_MODE_VERSION;

package/dist/decision.js

@@ -16,7 +16,7 @@ class DecisionSession {
     projection = new projections_1.DecisionProjection();
     constructor(client, options = {}) {
         this.client = client;
-        if (options.sessionId)
+        if (options.sessionId !== undefined)
             (0, validation_1.validateSessionId)(options.sessionId);
         this.sessionId = options.sessionId ?? (0, envelope_1.newSessionId)();
         this.modeVersion = options.modeVersion ?? constants_1.DEFAULT_MODE_VERSION;

package/dist/handoff.js

@@ -16,7 +16,7 @@ class HandoffSession {
     projection = new handoff_1.HandoffProjection();
     constructor(client, options = {}) {
         this.client = client;
-        if (options.sessionId)
+        if (options.sessionId !== undefined)
             (0, validation_1.validateSessionId)(options.sessionId);
         this.sessionId = options.sessionId ?? (0, envelope_1.newSessionId)();
         this.modeVersion = options.modeVersion ?? constants_1.DEFAULT_MODE_VERSION;

package/dist/projections/base.d.ts

@@ -1,5 +1,53 @@
 import type { ProtoRegistry } from '../proto-registry';
 import type { Envelope } from '../types';
+/**
+ * The kind of cardinality anomaly a projection recorded while replaying an
+ * accepted transcript. Cross-SDK frozen contract (`macp-sdk-python` adopted
+ * the identical field set, snake_case there) — do not add a kind without
+ * cross-SDK agreement.
+ */
+export type ProjectionAnomalyKind = 'duplicate_vote' | 'duplicate_ballot';
+/**
+ * A recorded observation that a second distinct `Vote` from this sender for
+ * this proposal (RFC-MACP-0007 §5.3), or a second distinct ballot across
+ * `Approve`/`Reject`/`Abstain` from this sender for this request
+ * (RFC-MACP-0011 §5 rule 3), was observed and discarded — the first stands.
+ * (RFC-MACP-0011 §5 rule 3 caps *how many* ballots and is silent on *which of
+ * two* stands; first-ballot-wins here is parity with RFC-MACP-0007 §5.3 plus
+ * runtime-enforced behaviour.)
+ *
+ * **Deliberately narrow claim — do not overclaim "this transcript violates
+ * the spec".** A projection cannot tell a genuinely non-conforming source
+ * from a conforming source fed through an unfiltered loader, because
+ * acceptance is not a wire property (`Envelope` carries no acceptance
+ * marker — see `applyEnvelope`'s "Input contract: accepted-only" docblock).
+ * An anomaly records only what was observed and what this projection did
+ * about it (discarded the second one, kept the first); it does not, and
+ * structurally cannot, assert that a conforming runtime was actually
+ * bypassed. Both `macp-sdk-python` and this SDK state it in these terms —
+ * agreed cross-SDK wording, not a style preference.
+ *
+ * Cross-SDK frozen contract, seven fields (camelCase here, snake_case in
+ * `macp-sdk-python`). Do not add, rename, or remove a field without
+ * cross-SDK agreement.
+ *
+ * Only `DecisionProjection` and `QuorumProjection` populate this today.
+ */
+export interface ProjectionAnomaly {
+    kind: ProjectionAnomalyKind;
+    mode: string;
+    messageType: string;
+    messageId: string;
+    sender: string;
+    /** `proposal_id` (Decision) or `request_id` (Quorum) the duplicate targeted. */
+    subjectId: string;
+    /**
+     * Human-readable detail. For a cross-type Quorum duplicate, `messageType`
+     * is what distinguishes the discarded ballot's type (Approve/Reject/Abstain)
+     * from the kept one — `detail` should name both.
+     */
+    detail: string;
+}
 /**
  * Abstract base for in-process mode-state tracking — parity with python-sdk's
  * `macp_sdk.base_projection.BaseProjection`. Maintains a shared transcript,
@@ -8,13 +56,114 @@ import type { Envelope } from '../types';
  * handled here so custom modes get the common lifecycle for free.
  */
 export declare abstract class BaseProjection {
+    /**
+     * The session's accepted history as a conforming runtime holds it: one
+     * envelope per unique `message_id`, in application order. Redelivered
+     * envelopes (same `message_id` — expected under MACP's at-least-once
+     * delivery, RFC-MACP-0001 §8, and normatively idempotent per RFC-MACP-0006
+     * §3.2 Redelivery) and envelopes for other modes are not appended; a
+     * redelivery is logged at debug level and has no effect on projection
+     * state.
+     */
     readonly transcript: Envelope[];
     phase: string;
     commitment?: Record<string, unknown>;
+    /**
+     * `message_id`s already applied to this projection, used to make
+     * `applyEnvelope` idempotent under redelivery (RFC-MACP-0006 §3.2:
+     * "A consumer that accumulates state per envelope ... MUST be idempotent
+     * with respect to `message_id`", `:136`). Deliberately unbounded: this
+     * class already retains every full envelope (payload bytes included) in
+     * `transcript`, so a set of id strings is strictly dominated by that; the
+     * runtime keeps an unbounded per-message dedup set itself
+     * (`macp-runtime/crates/macp-modes/src/step.rs:48/:89`, field declared at
+     * `crates/macp-core/src/session.rs:69`), and sessions are TTL-bounded by
+     * protocol.
+     */
+    private readonly seenMessageIds;
+    /**
+     * 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.
+     */
+    readonly anomalies: ProjectionAnomaly[];
     protected abstract readonly mode: string;
+    /**
+     * 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
+     * `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
+     * that claim).
+     */
+    get hasAnomalies(): boolean;
     get isCommitted(): boolean;
     get isPositiveOutcome(): boolean | undefined;
+    /**
+     * Apply one envelope to this projection's in-process state.
+     *
+     * ## Input contract: accepted-only
+     *
+     * `applyEnvelope` assumes every envelope it is given was **accepted** by a
+     * conforming MACP runtime — i.e. it is part of the session's authoritative
+     * accepted history, never a submission the runtime rejected. This is a
+     * **caller-maintained invariant**, not something this method can check:
+     * `Envelope` (`src/types.ts`) carries no acceptance marker on the wire, so a
+     * projection has no field to inspect to tell an accepted envelope from a
+     * rejected one. Canonical source, verbatim: `schemas/conformance/README.md`
+     * "Notes:" — "SDKs replay only `accept` messages through their projections
+     * (reject-path fixtures replay their accepted *prefix*)." The rule this
+     * supports is spelled out in RFC-MACP-0007 §5 rule 3 (this repo's shorthand:
+     * "§5.3" — the RFC has no literal `### 5.3` heading) — "the first accepted
+     * `Vote` stands" — and RFC-MACP-0011 §5 rule 3 — at most one ballot per
+     * participant. Both describe what a conforming runtime enforces on ACCEPTED
+     * history; a projection reconstructing that history is only correct when fed
+     * the same set the runtime held.
+     *
+     * This SDK's own send paths uphold the invariant already: each of the five
+     * built-in mode sessions has its own private `sendAndTrack` that calls
+     * `this.projection.applyEnvelope(...)` only `if (ack.ok)`. `BaseSession`'s
+     * own `sendAndTrack` (`src/base-session.ts`) — the equivalent path for
+     * custom modes built on the ext-mode extension point — does the same. The
+     * conformance harness upholds it too: its `acceptedMessages` filter in
+     * `tests/conformance/conformance.test.ts` keeps only messages with
+     * `expect === 'accept'` before replay.
+     *
+     * **Failure mode if the contract is violated:** wiring this method to raw
+     * captured or hand-built traffic — including envelopes a runtime rejected —
+     * replays a timeline that no conforming runtime ever held, fabricating
+     * projection state. Concretely: a session whose only `Commitment` was
+     * rejected can still end up with `isCommitted === true` and
+     * `phase === 'Committed'` if that rejected envelope is replayed anyway. See
+     * `tests/unit/projections/accepted-only-contract.test.ts` for an executable
+     * demonstration, both with the corruption present and with it avoided.
+     *
+     * @param envelope - MUST be an envelope the runtime accepted; the caller is
+     * responsible for filtering out rejected submissions before calling this
+     * method. Envelopes for a different `mode` are ignored (the `if
+     * (envelope.mode !== this.mode) return;` guard below, in this method's own
+     * body), but that check is unrelated to this contract and does not
+     * substitute for it.
+     */
     applyEnvelope(envelope: Envelope, protoRegistry: ProtoRegistry): void;
     /** Handle a mode-specific (non-Commitment) envelope. */
     protected abstract applyMode(envelope: Envelope, protoRegistry: ProtoRegistry): void;
+    /**
+     * Record a cardinality anomaly: push it onto `anomalies` and emit it via
+     * `logger.warn('projection anomaly', anomaly)`. The `anomalies` array is
+     * the canonical, cross-SDK-agreed semantic; the log call is explicitly
+     * NON-contractual observability and may differ per SDK. `logger.warn` is
+     * visible by default (this SDK's default log level is `warn`,
+     * `src/logging.ts`) — observing and discarding a duplicate is deliberately
+     * not silent. To quiet it without losing the `anomalies` array, configure a
+     * higher level: `configureLogging({ level: 'error' })` or the
+     * `MACP_LOG_LEVEL` environment variable.
+     */
+    protected recordAnomaly(anomaly: ProjectionAnomaly): void;
 }

package/dist/projections/base.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseProjection = void 0;
+const logging_1 = require("../logging");
 /**
  * Abstract base for in-process mode-state tracking — parity with python-sdk's
  * `macp_sdk.base_projection.BaseProjection`. Maintains a shared transcript,
@@ -9,9 +10,54 @@ exports.BaseProjection = void 0;
  * handled here so custom modes get the common lifecycle for free.
  */
 class BaseProjection {
+    /**
+     * The session's accepted history as a conforming runtime holds it: one
+     * envelope per unique `message_id`, in application order. Redelivered
+     * envelopes (same `message_id` — expected under MACP's at-least-once
+     * delivery, RFC-MACP-0001 §8, and normatively idempotent per RFC-MACP-0006
+     * §3.2 Redelivery) and envelopes for other modes are not appended; a
+     * redelivery is logged at debug level and has no effect on projection
+     * state.
+     */
     transcript = [];
     phase = '';
     commitment;
+    /**
+     * `message_id`s already applied to this projection, used to make
+     * `applyEnvelope` idempotent under redelivery (RFC-MACP-0006 §3.2:
+     * "A consumer that accumulates state per envelope ... MUST be idempotent
+     * with respect to `message_id`", `:136`). Deliberately unbounded: this
+     * class already retains every full envelope (payload bytes included) in
+     * `transcript`, so a set of id strings is strictly dominated by that; the
+     * runtime keeps an unbounded per-message dedup set itself
+     * (`macp-runtime/crates/macp-modes/src/step.rs:48/:89`, field declared at
+     * `crates/macp-core/src/session.rs:69`), and sessions are TTL-bounded by
+     * protocol.
+     */
+    seenMessageIds = new Set();
+    /**
+     * 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.
+     */
+    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
+     * `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
+     * that claim).
+     */
+    get hasAnomalies() {
+        return this.anomalies.length > 0;
+    }
     get isCommitted() {
         return this.commitment !== undefined;
     }
@@ -22,9 +68,74 @@ class BaseProjection {
             this.commitment.outcome_positive;
         return val !== undefined ? Boolean(val) : true;
     }
+    /**
+     * Apply one envelope to this projection's in-process state.
+     *
+     * ## Input contract: accepted-only
+     *
+     * `applyEnvelope` assumes every envelope it is given was **accepted** by a
+     * conforming MACP runtime — i.e. it is part of the session's authoritative
+     * accepted history, never a submission the runtime rejected. This is a
+     * **caller-maintained invariant**, not something this method can check:
+     * `Envelope` (`src/types.ts`) carries no acceptance marker on the wire, so a
+     * projection has no field to inspect to tell an accepted envelope from a
+     * rejected one. Canonical source, verbatim: `schemas/conformance/README.md`
+     * "Notes:" — "SDKs replay only `accept` messages through their projections
+     * (reject-path fixtures replay their accepted *prefix*)." The rule this
+     * supports is spelled out in RFC-MACP-0007 §5 rule 3 (this repo's shorthand:
+     * "§5.3" — the RFC has no literal `### 5.3` heading) — "the first accepted
+     * `Vote` stands" — and RFC-MACP-0011 §5 rule 3 — at most one ballot per
+     * participant. Both describe what a conforming runtime enforces on ACCEPTED
+     * history; a projection reconstructing that history is only correct when fed
+     * the same set the runtime held.
+     *
+     * This SDK's own send paths uphold the invariant already: each of the five
+     * built-in mode sessions has its own private `sendAndTrack` that calls
+     * `this.projection.applyEnvelope(...)` only `if (ack.ok)`. `BaseSession`'s
+     * own `sendAndTrack` (`src/base-session.ts`) — the equivalent path for
+     * custom modes built on the ext-mode extension point — does the same. The
+     * conformance harness upholds it too: its `acceptedMessages` filter in
+     * `tests/conformance/conformance.test.ts` keeps only messages with
+     * `expect === 'accept'` before replay.
+     *
+     * **Failure mode if the contract is violated:** wiring this method to raw
+     * captured or hand-built traffic — including envelopes a runtime rejected —
+     * replays a timeline that no conforming runtime ever held, fabricating
+     * projection state. Concretely: a session whose only `Commitment` was
+     * rejected can still end up with `isCommitted === true` and
+     * `phase === 'Committed'` if that rejected envelope is replayed anyway. See
+     * `tests/unit/projections/accepted-only-contract.test.ts` for an executable
+     * demonstration, both with the corruption present and with it avoided.
+     *
+     * @param envelope - MUST be an envelope the runtime accepted; the caller is
+     * responsible for filtering out rejected submissions before calling this
+     * method. Envelopes for a different `mode` are ignored (the `if
+     * (envelope.mode !== this.mode) return;` guard below, in this method's own
+     * body), but that check is unrelated to this contract and does not
+     * substitute for it.
+     */
     applyEnvelope(envelope, protoRegistry) {
         if (envelope.mode !== this.mode)
             return;
+        // RFC-MACP-0006 §3.2 Redelivery (`:94`, `:134`-`:136`): a runtime MAY echo
+        // back accepted envelopes, a redelivery MUST NOT advance sequence position
+        // or count a second time against cardinality, and a consumer that
+        // accumulates state per envelope MUST be idempotent w.r.t. `message_id`.
+        // The `if (envelope.messageId)` guard is mandatory: an empty/absent id
+        // must apply WITHOUT dedup, or a feed of empty-id envelopes collapses to
+        // one. This is architecturally expected (RFC-MACP-0001:306 at-least-once
+        // delivery), not an anomaly — hence `debug`, never `warn`.
+        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);
         if (envelope.messageType === 'Commitment') {
             this.commitment = protoRegistry.decodeKnownPayload(envelope.mode, envelope.messageType, envelope.payload);
@@ -33,5 +144,20 @@ class BaseProjection {
         }
         this.applyMode(envelope, protoRegistry);
     }
+    /**
+     * Record a cardinality anomaly: push it onto `anomalies` and emit it via
+     * `logger.warn('projection anomaly', anomaly)`. The `anomalies` array is
+     * the canonical, cross-SDK-agreed semantic; the log call is explicitly
+     * NON-contractual observability and may differ per SDK. `logger.warn` is
+     * visible by default (this SDK's default log level is `warn`,
+     * `src/logging.ts`) — observing and discarding a duplicate is deliberately
+     * not silent. To quiet it without losing the `anomalies` array, configure a
+     * higher level: `configureLogging({ level: 'error' })` or the
+     * `MACP_LOG_LEVEL` environment variable.
+     */
+    recordAnomaly(anomaly) {
+        this.anomalies.push(anomaly);
+        logging_1.logger.warn('projection anomaly', anomaly);
+    }
 }
 exports.BaseProjection = BaseProjection;

package/dist/projections/decision.d.ts

@@ -1,3 +1,4 @@
+import type { ProjectionAnomaly } from './base';
 import type { Envelope } from '../types';
 import type { ProtoRegistry } from '../proto-registry';
 export interface DecisionProposalRecord {
@@ -30,10 +31,52 @@ export declare class DecisionProjection {
     readonly evaluations: DecisionEvaluationRecord[];
     readonly objections: DecisionObjectionRecord[];
     readonly votes: Map<string, Map<string, DecisionVoteRecord>>;
+    /**
+     * 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 `Vote` from the same sender for the same
+     * `proposal_id`). See `BaseProjection.anomalies` (`src/projections/base.ts`)
+     * for the canonical description; duplicated here only as a one-line
+     * pointer.
+     */
+    readonly anomalies: ProjectionAnomaly[];
     phase: 'Proposal' | 'Evaluation' | '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;
     voteTotals(): Record<string, number>;

package/dist/projections/decision.js

@@ -2,17 +2,65 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DecisionProjection = void 0;
 const constants_1 = require("../constants");
+const logging_1 = require("../logging");
 class DecisionProjection {
     proposals = new Map();
     evaluations = [];
     objections = [];
     votes = 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 `Vote` from the same sender for the same
+     * `proposal_id`). See `BaseProjection.anomalies` (`src/projections/base.ts`)
+     * for the canonical description; duplicated here only as a one-line
+     * pointer.
+     */
+    anomalies = [];
     phase = 'Proposal';
     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_DECISION)
             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);
         const payload = protoRegistry.decodeKnownPayload(envelope.mode, envelope.messageType, envelope.payload);
         switch (envelope.messageType) {
@@ -40,6 +88,25 @@ class DecisionProjection {
             case 'Vote': {
                 const record = payload;
                 const bySender = this.votes.get(record.proposalId) ?? new Map();
+                const kept = bySender.get(envelope.sender);
+                if (kept !== undefined) {
+                    // RFC-MACP-0007 §5 item 3: the first accepted Vote stands. A conforming
+                    // runtime NACKs the duplicate (macp-runtime decision.rs), so reaching
+                    // here means the transcript was not filtered to a conforming
+                    // runtime's accepted history.
+                    const anomaly = {
+                        kind: 'duplicate_vote',
+                        mode: envelope.mode,
+                        messageType: envelope.messageType,
+                        messageId: envelope.messageId,
+                        sender: envelope.sender,
+                        subjectId: record.proposalId,
+                        detail: `sender ${envelope.sender} already voted '${kept.vote}' on proposal ${record.proposalId}; discarded '${record.vote}'`,
+                    };
+                    this.anomalies.push(anomaly);
+                    logging_1.logger.warn('projection anomaly', anomaly);
+                    break;
+                }
                 bySender.set(envelope.sender, { ...record, sender: envelope.sender });
                 this.votes.set(record.proposalId, bySender);
                 this.phase = 'Voting';
@@ -54,6 +121,14 @@ class DecisionProjection {
                 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;
     }

package/dist/projections/handoff.d.ts

@@ -1,3 +1,4 @@
+import type { ProjectionAnomaly } from './base';
 import type { Envelope } from '../types';
 import type { ProtoRegistry } from '../proto-registry';
 export interface HandoffRecord {
@@ -19,10 +20,51 @@ export interface HandoffRecord {
 }
 export declare class HandoffProjection {
     readonly handoffs: Map<string, HandoffRecord>;
+    /**
+     * 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 Handoff mode.
+     */
+    readonly anomalies: ProjectionAnomaly[];
     phase: 'Pending' | 'OfferPending' | 'ContextSharing' | 'Accepted' | 'Declined' | '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;
     getHandoff(handoffId: string): HandoffRecord | undefined;