macp-sdk-typescript 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,100 @@ 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.9.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.8.0...v0.9.0) (2026-09-01)
+
+
+### ⚠ BREAKING CHANGES
+
+* **projections:** ProposalProjection.isAccepted()/acceptedProposal(), TaskProjection's `assignee` field, and HandoffProjection's `status` field can now derive different values than before for a transcript containing the message sequences described above. Conforming transcripts (no superseded accept, no second TaskAccept/contradictory handoff accept-decline) are unaffected.
+
+### Bug Fixes
+
+* **agent:** don't count an envelope into the resume cursor until it's asked for again ([#72](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/72)) ([f1b7015](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/f1b70155cb3293bc7f36c0389cbf880359a01e58)), closes [#66](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/66)
+* **agent:** resume GrpcTransportAdapter from its own cursor, and count distinct envelopes ([#65](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/65)) ([7535763](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/75357632351addde3a32a61b1200e823f2ef70da))
+* **projections:** enforce cardinality rules issues [#59](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/59)/[#60](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/60) said didn't exist ([#68](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/68)) ([956d881](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/956d881e19591bcd9a04c6496bff07213d1ee6d3))
+
+## [Unreleased]
+
+### Fixed
+
+- **BREAKING: four projection sites now enforce the cardinality rule their
+  governing RFC section actually states, instead of last-write-wins.**
+  Issues #59 and #60 argued that no cardinality/ordering site in the
+  built-in projections had a normative rule behind it; a full re-read of the
+  four mode RFCs plus RFC-MACP-0001 found governing rules for five of the
+  ten sites they raised, three of which were shipped conformance
+  violations:
+  - `ProposalProjection` (breaking): a later `Accept` from a participant now
+    supersedes their earlier one (RFC-MACP-0008 §5 rule 5, `:70`), so
+    `isAccepted` and `acceptedProposal()` read the live acceptance set
+    instead of raw accept history. Previously `acceptedProposal()` could
+    return `undefined` after a legal re-accept, where the RFC's
+    determinism clause (§7, `:89`) makes the accepted proposal unambiguous.
+  - `TaskProjection` (breaking): the first accepted `TaskAccept` now wins —
+    a later `TaskAccept` for the same task no longer overwrites `assignee`
+    (RFC-MACP-0009 §5 rules 3/3a, `:69-71`). The policy-gated reassignment
+    path (rule 3c) is intentionally not modelled yet; `TaskProjection` has
+    no session-policy input.
+  - `HandoffProjection` (breaking): a `handoff_id` now settles (`offered` →
+    `accepted`/`declined`) exactly once — a later contradictory
+    `HandoffAccept`/`HandoffDecline` for an already-settled `handoff_id`,
+    or for a `handoff_id` that was never offered, is ignored in both
+    directions and can no longer mutate `phase` (RFC-MACP-0010 §5 rule 2
+    `:65`, rule 4 `:68`, §5.1(4) `:113-116`).
+  - `DecisionProjection` (not breaking for conforming callers): `phase` no
+    longer regresses out of `'Committed'` if a `Vote` is replayed after a
+    `Commitment` — such a message cannot legally exist in accepted history
+    under a conforming runtime (RFC-MACP-0001 §7.2 `:218`, §7.3
+    `:240`/`:249`), but a caller violating the accepted-only contract no
+    longer corrupts `phase` if it happens.
+
+  `ProposalProjection.isAccepted()`/`acceptedProposal()`, `TaskProjection`'s
+  `assignee` field, and `HandoffProjection`'s `status`/`phase` can now
+  derive different values than before for a transcript containing the
+  message sequences described above — existing callers reading those
+  surfaces should treat this as a breaking change. Conforming transcripts
+  (no superseded accept, no second `TaskAccept`, no contradictory or
+  unknown-`handoff_id` handoff accept/decline) are unaffected.
+
+  Three other sites raised by #59 (Decision `Evaluation`/`Objection`
+  cardinality, Task `TaskUpdate` accumulation) were confirmed to be silent
+  *coherently* and are unchanged. `TaskComplete`/`TaskFail` cardinality is
+  genuinely ambiguous in RFC-MACP-0009 and is tracked as an upstream spec
+  question rather than an SDK change.
+
+### Changed
+
+- **`GrpcTransportAdapter` resumes instead of replaying on a second `start()`.**
+  The adapter now calls `sendSubscribe(sessionId, this.lastSequence)` instead of
+  always subscribing from `0`, so a caller that `stop()`s and re-`start()`s a
+  reused adapter — the only reachable "reconnect" in this SDK; there is no
+  built-in retry loop — no longer replays the entire session history. Requires
+  `macp-runtime` ≥ 0.5.0 for the `after_sequence` ordinal contract
+  (RFC-MACP-0006 §3.2); older runtimes compared it inclusively against a raw
+  log index. `lastSequence` itself is corrected in the same change to count
+  **distinct** accepted envelopes (keyed on `message_id`) instead of raw
+  delivery events — passing the old, uncorrected counter as a resume cursor
+  would have silently skipped history on resume (RFC-MACP-0006 §3.2
+  Redelivery). Anyone relying on a reused adapter's second `start()` to rebuild
+  a *fresh* projection from full history will now see only the envelopes
+  accepted since the first pass ended; open a new `GrpcTransportAdapter` (or a
+  raw `MacpStream` with `sendSubscribe(sessionId, 0)`) for a full replay.
+- `MacpStream.sendSubscribe`'s docblock no longer claims `IncomingMessage.seq`
+  is the RFC-MACP-0006 ordinal — `seq` is a 0-based delivery index that
+  advances on redelivery, unlike the ordinal.
+
+## [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)
 
 

package/README.md

@@ -367,7 +367,7 @@ await stream.sendSubscribe(sessionId);            // full replay then live
 await stream.sendSubscribe(sessionId, lastSeq);    // resume from cursor
 ```
 
-The agent framework's `GrpcTransportAdapter` calls this for you on start, so non-initiator agents see `SessionStart` regardless of join order.
+The agent framework's `GrpcTransportAdapter` calls this for you on start, so non-initiator agents see `SessionStart` regardless of join order — and it passes its own resume cursor on a second `start()` (after a `stop()`), so that call resumes rather than replaying the whole session again.
 
 ### Registry & Root Watchers
 

package/dist/agent/transports.d.ts

@@ -12,14 +12,39 @@ export declare class GrpcTransportAdapter implements TransportAdapter {
     private stream;
     private seq;
     private delivered;
+    /**
+     * `message_id`s already counted into `delivered`, so the resume cursor
+     * advances once per distinct accepted envelope rather than once per raw
+     * delivery (RFC-MACP-0006 §3.2 Redelivery). Deliberately unbounded, for the
+     * same reason `BaseProjection` leaves its own copy of this set unbounded
+     * (`src/projections/base.ts:118-129`): this set is strictly dominated by
+     * memory this SDK already commits to per session — a `Participant` using
+     * this adapter also holds a `BaseProjection` with an identical
+     * `message_id` set *plus* a full `transcript` of every envelope, payload
+     * bytes included. The runtime keeps an unbounded per-session dedup set of
+     * its own regardless of what any client does
+     * (`macp-runtime/crates/macp-modes/src/step.rs:48/:89`, field declared at
+     * `macp-runtime/crates/macp-core/src/session.rs:69`), and sessions are
+     * TTL-bounded by protocol.
+     */
+    private readonly seenMessageIds;
     constructor(client: MacpClient, sessionId: string, auth?: AuthConfig | undefined);
     /**
      * The server passive-subscribe ordinal of the last delivered envelope (the
-     * 1-based count of accepted envelopes delivered on this stream, RFC-MACP-0006
-     * §3.2). `0` before anything is delivered. Pass this as `afterSequence` to
-     * `MacpStream.sendSubscribe` on a reconnect to resume exactly-once — ordinals
-     * are stable across compaction/restart. Distinct from `IncomingMessage.seq`,
-     * which is a client-local 0-based delivery index.
+     * 1-based count of *distinct* accepted envelopes delivered on this stream,
+     * RFC-MACP-0006 §3.2). `0` before anything is delivered. `start()` passes
+     * this value as `afterSequence` to `MacpStream.sendSubscribe` itself, so a
+     * caller that `stop()`s and calls `start()` again (the only reachable
+     * "reconnect" in this SDK — there is no built-in retry loop) resumes
+     * rather than replays the whole session. Ordinals are stable across
+     * compaction/restart. Counts distinct `message_id`s, never raw delivery
+     * events: RFC-MACP-0006 §3.2 Redelivery requires that "a redelivery MUST
+     * NOT advance the client's sequence position; only a distinct accepted
+     * envelope does," and a client that counts raw deliveries "arrives at a
+     * position ahead of the true one, and its next resume silently skips
+     * history." Distinct from `IncomingMessage.seq`, which is a client-local
+     * 0-based delivery index that advances on every delivery, redeliveries
+     * included.
      */
     get lastSequence(): number;
     start(): AsyncIterable<IncomingMessage>;

package/dist/agent/transports.js

@@ -19,6 +19,22 @@ class GrpcTransportAdapter {
     stream = null;
     seq = 0;
     delivered = 0;
+    /**
+     * `message_id`s already counted into `delivered`, so the resume cursor
+     * advances once per distinct accepted envelope rather than once per raw
+     * delivery (RFC-MACP-0006 §3.2 Redelivery). Deliberately unbounded, for the
+     * same reason `BaseProjection` leaves its own copy of this set unbounded
+     * (`src/projections/base.ts:118-129`): this set is strictly dominated by
+     * memory this SDK already commits to per session — a `Participant` using
+     * this adapter also holds a `BaseProjection` with an identical
+     * `message_id` set *plus* a full `transcript` of every envelope, payload
+     * bytes included. The runtime keeps an unbounded per-session dedup set of
+     * its own regardless of what any client does
+     * (`macp-runtime/crates/macp-modes/src/step.rs:48/:89`, field declared at
+     * `macp-runtime/crates/macp-core/src/session.rs:69`), and sessions are
+     * TTL-bounded by protocol.
+     */
+    seenMessageIds = new Set();
     constructor(client, sessionId, auth) {
         this.client = client;
         this.sessionId = sessionId;
@@ -26,27 +42,92 @@ class GrpcTransportAdapter {
     }
     /**
      * The server passive-subscribe ordinal of the last delivered envelope (the
-     * 1-based count of accepted envelopes delivered on this stream, RFC-MACP-0006
-     * §3.2). `0` before anything is delivered. Pass this as `afterSequence` to
-     * `MacpStream.sendSubscribe` on a reconnect to resume exactly-once — ordinals
-     * are stable across compaction/restart. Distinct from `IncomingMessage.seq`,
-     * which is a client-local 0-based delivery index.
+     * 1-based count of *distinct* accepted envelopes delivered on this stream,
+     * RFC-MACP-0006 §3.2). `0` before anything is delivered. `start()` passes
+     * this value as `afterSequence` to `MacpStream.sendSubscribe` itself, so a
+     * caller that `stop()`s and calls `start()` again (the only reachable
+     * "reconnect" in this SDK — there is no built-in retry loop) resumes
+     * rather than replays the whole session. Ordinals are stable across
+     * compaction/restart. Counts distinct `message_id`s, never raw delivery
+     * events: RFC-MACP-0006 §3.2 Redelivery requires that "a redelivery MUST
+     * NOT advance the client's sequence position; only a distinct accepted
+     * envelope does," and a client that counts raw deliveries "arrives at a
+     * position ahead of the true one, and its next resume silently skips
+     * history." Distinct from `IncomingMessage.seq`, which is a client-local
+     * 0-based delivery index that advances on every delivery, redeliveries
+     * included.
      */
     get lastSequence() {
         return this.delivered;
     }
     async *start() {
+        // A prior stream from an earlier start() (without an intervening stop())
+        // must not keep feeding this adapter's counter — two live generators
+        // would both advance `delivered` from two differently-positioned
+        // replays. `MacpStream.close()` is `this.call.end()` (`src/client.ts:223-227`),
+        // a write-side half-close — it does not itself force the server to stop
+        // pushing. It is enough here because macp-runtime's StreamSession loop
+        // reads the resulting end-of-request-stream as `StreamAction::ClientDone`,
+        // whose arm drains any already-buffered envelopes once and then breaks,
+        // ending that stream's response side too
+        // (macp-runtime/src/server.rs:654-666). Close it before opening the new
+        // one so re-entrant start() and stop()-then-start() behave identically.
+        if (this.stream) {
+            this.stream.close();
+            this.stream = null;
+        }
         this.stream = this.client.openStream({ auth: this.auth });
-        // RFC-MACP-0006-A1: Subscribe to the session with history replay.
-        // The runtime replays accepted envelopes then switches to live broadcast.
-        // This ensures non-initiator agents receive the SessionStart + Proposal
-        // regardless of spawn order or connection timing.
-        await this.stream.sendSubscribe(this.sessionId);
+        // RFC-MACP-0006 §3.2: subscribe to the session, resuming from this
+        // adapter's own cursor. `this.delivered` is 0 before anything has been
+        // delivered, by construction, and `afterSequence = 0` is normatively
+        // "replay from the session's first accepted envelope" — so the first
+        // subscribe and every later one (e.g. after stop()+start()) are the same
+        // expression. There is no separate first-subscribe/reconnect branch to
+        // keep in sync with the counter.
+        await this.stream.sendSubscribe(this.sessionId, this.delivered);
         for await (const envelope of this.stream.responses()) {
             if (envelope.sessionId !== this.sessionId)
                 continue;
-            this.delivered++;
-            yield normalizeEnvelope(envelope, (mode, mt, p) => this.client.protoRegistry.decodeKnownPayload(mode, mt, p), this.seq++);
+            // Count this envelope into the resume cursor only *after* the
+            // consumer has come back for more, not when it is handed off. `yield`
+            // suspends here until the consumer's `for await` either calls
+            // `.next()` again (it took this envelope and kept iterating — the
+            // code below runs) or closes the iterator via `break`/`return`/throw
+            // (e.g. `Participant.run()` observing `!this.running` and breaking
+            // out of its loop without processing this envelope). In the latter
+            // case `.return()` on this generator resumes at this `yield` as if a
+            // `return` had been written here, so nothing below it runs: the
+            // cursor is never advanced past an envelope the consumer never
+            // actually took past the loop boundary, and the next `start()`
+            // redelivers it instead of silently skipping it. See #66 — counting
+            // before yielding let a stop-mid-stream permanently drop an envelope
+            // once #65 made the resume cursor authoritative.
+            const message = normalizeEnvelope(envelope, (mode, mt, p) => this.client.protoRegistry.decodeKnownPayload(mode, mt, p), this.seq++);
+            yield message;
+            // RFC-MACP-0006 §3.2 Redelivery: a redelivery MUST NOT advance the
+            // resume cursor, and a consumer that accumulates state per envelope
+            // MUST be idempotent w.r.t. `message_id`. An empty/absent messageId
+            // has no identity to dedup on and increments unconditionally — the
+            // same carve-out the projection guard documents at
+            // `src/projections/base.ts:224-227`, so the two dedup sites read the
+            // same way. In practice the `else` below can never run against a
+            // conformant runtime: `validate_envelope_shape` rejects any envelope
+            // with an empty `message_id` as `InvalidEnvelope` before it can be
+            // accepted (`macp-runtime/src/server.rs:118`), and RFC-MACP-0001 §8.2
+            // makes `message_id` the runtime's dedup identity, so no accepted
+            // envelope in any session history can carry one. The branch stays
+            // anyway — it costs nothing and errs toward still counting the
+            // envelope instead of silently dropping it if a non-conformant server
+            // ever sends one.
+            if (envelope.messageId) {
+                if (!this.seenMessageIds.has(envelope.messageId)) {
+                    this.seenMessageIds.add(envelope.messageId);
+                    this.delivered++;
+                }
+            }
+            else {
+                this.delivered++;
+            }
         }
     }
     async stop() {
@@ -88,6 +169,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 +185,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/client.d.ts

@@ -48,9 +48,13 @@ export declare class MacpStream {
      *
      * `afterSequence` is the **1-based accepted-envelope ordinal**, exclusive:
      * `0` (default) replays from the very start; `k` replays envelopes with
-     * ordinal `> k`. Clients derive the ordinal by counting delivered envelopes
-     * (the Nth accepted envelope has ordinal N) — see
-     * `IncomingMessage.seq`, which is exactly this ordinal under the new contract.
+     * ordinal `> k`. Clients derive the ordinal by counting **distinct**
+     * accepted envelopes delivered, keyed on `message_id` — RFC-MACP-0006 §3.2
+     * Redelivery requires that a repeat of an already-observed envelope MUST
+     * NOT advance the count. This is **not** the same as `IncomingMessage.seq`,
+     * which is a client-local 0-based delivery index that advances on every
+     * delivery, redeliveries included; see `GrpcTransportAdapter.lastSequence`
+     * for a cursor that tracks the ordinal correctly.
      * Ordinals are stable across log compaction and runtime restart. Resuming
      * below a compacted base returns `FAILED_PRECONDITION` (inspectable via
      * `MacpTransportError.code`) rather than silently skipping history (runtime

package/dist/client.js

@@ -160,9 +160,13 @@ class MacpStream {
      *
      * `afterSequence` is the **1-based accepted-envelope ordinal**, exclusive:
      * `0` (default) replays from the very start; `k` replays envelopes with
-     * ordinal `> k`. Clients derive the ordinal by counting delivered envelopes
-     * (the Nth accepted envelope has ordinal N) — see
-     * `IncomingMessage.seq`, which is exactly this ordinal under the new contract.
+     * ordinal `> k`. Clients derive the ordinal by counting **distinct**
+     * accepted envelopes delivered, keyed on `message_id` — RFC-MACP-0006 §3.2
+     * Redelivery requires that a repeat of an already-observed envelope MUST
+     * NOT advance the count. This is **not** the same as `IncomingMessage.seq`,
+     * which is a client-local 0-based delivery index that advances on every
+     * delivery, redeliveries included; see `GrpcTransportAdapter.lastSequence`
+     * for a cursor that tracks the ordinal correctly.
      * Ordinals are stable across log compaction and runtime restart. Resuming
      * below a compacted base returns `FAILED_PRECONDITION` (inspectable via
      * `MacpTransportError.code`) rather than silently skipping history (runtime

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;
 }