macp-sdk-typescript 0.7.1 → 0.9.0

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,9 +88,44 @@ 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';
+                // RFC-MACP-0001 §7.2 (`:218`): RESOLVED is terminal and sessions
+                // MUST transition monotonically w.r.t. termination — never back to
+                // OPEN/SUSPENDED. §7.3 (`:240`, restated `:249`) says a conforming
+                // runtime rejects any session-scoped message once the session is
+                // non-OPEN, so a `Vote` cannot legally follow a `Commitment` in
+                // accepted history. If one reaches here anyway (the caller violated
+                // the accepted-only contract — see `applyEnvelope`'s docblock), do
+                // not regress `phase` out of `'Committed'`. Note "phase" itself is
+                // not a normative MACP term (it appears once, in passing, at
+                // RFC-MACP-0012 `:211`); this guard is justified by session
+                // terminality, not by a phase specification. An anomaly would be
+                // recorded here too, but `ProjectionAnomalyKind` (`base.ts:8-9`) is
+                // deliberately frozen pending cross-SDK agreement with
+                // macp-sdk-python.
+                if (this.phase !== 'Committed') {
+                    this.phase = 'Voting';
+                }
                 break;
             }
             case 'Commitment': {
@@ -54,6 +137,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;

package/dist/projections/handoff.js

@@ -2,14 +2,61 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HandoffProjection = void 0;
 const constants_1 = require("../constants");
+const logging_1 = require("../logging");
 class HandoffProjection {
     handoffs = 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. 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.
+     */
+    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_HANDOFF)
             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) {
@@ -44,25 +91,61 @@ class HandoffProjection {
             case 'HandoffAccept': {
                 const record = payload;
                 const handoff = this.handoffs.get(record.handoffId);
-                if (handoff) {
+                if (!handoff) {
+                    // RFC-MACP-0010 §5 rule 2 (`:65`): "HandoffContext, HandoffAccept,
+                    // and HandoffDecline MUST reference an existing handoff_id." An
+                    // accept for an unknown/never-offered handoff_id is invalid input
+                    // (e.g. an unfiltered transcript) and MUST NOT mutate `phase` or
+                    // fabricate a handoff record. An anomaly would be recorded here,
+                    // but `ProjectionAnomalyKind` (`base.ts:8-9`) is deliberately
+                    // frozen pending cross-SDK agreement with macp-sdk-python.
+                    break;
+                }
+                // RFC-MACP-0010 §5 rule 4 (`:68`): "Once an offer has been
+                // accepted, no competing accept for that same `handoff_id` is
+                // valid." §5.1(4) (`:113-116`) settles the decline-after-accept
+                // direction too: a `handoff_id` transitions
+                // offered -> accepted | declined exactly once. Only settle if this
+                // handoff hasn't already resolved — the same shape as the
+                // HandoffContext guard just above. An anomaly would be recorded when
+                // this guard discards a competing accept, but `ProjectionAnomalyKind`
+                // (`base.ts:8-9`) is deliberately frozen pending cross-SDK agreement
+                // with macp-sdk-python.
+                if (handoff.status === 'offered' || handoff.status === 'context_sent') {
                     handoff.status = 'accepted';
                     handoff.acceptedBy = record.acceptedBy;
                     // proto3 bool defaults are materialized to `false` on decode
                     // (proto-registry), so this is always a real boolean once proto 0.1.6
                     // is loaded — `true` marks a runtime synthetic implicit accept.
                     handoff.implicit = record.implicit ?? false;
+                    this.phase = 'Accepted';
                 }
-                this.phase = 'Accepted';
                 break;
             }
             case 'HandoffDecline': {
                 const record = payload;
                 const handoff = this.handoffs.get(record.handoffId);
-                if (handoff) {
+                if (!handoff) {
+                    // RFC-MACP-0010 §5 rule 2 (`:65`): "HandoffContext, HandoffAccept,
+                    // and HandoffDecline MUST reference an existing handoff_id." A
+                    // decline for an unknown/never-offered handoff_id is invalid input
+                    // (e.g. an unfiltered transcript) and MUST NOT mutate `phase` or
+                    // fabricate a handoff record. An anomaly would be recorded here,
+                    // but `ProjectionAnomalyKind` (`base.ts:8-9`) is deliberately
+                    // frozen pending cross-SDK agreement with macp-sdk-python.
+                    break;
+                }
+                // RFC-MACP-0010 §5 rule 4 (`:68`) + §5.1(4) (`:113-116`): a
+                // `handoff_id` settles once. A decline after the handoff already
+                // settled (accepted or declined) is invalid and ignored. An anomaly
+                // would be recorded here too, but `ProjectionAnomalyKind`
+                // (`base.ts:8-9`) is deliberately frozen pending cross-SDK agreement
+                // with macp-sdk-python.
+                if (handoff.status === 'offered' || handoff.status === 'context_sent') {
                     handoff.status = 'declined';
                     handoff.declinedBy = record.declinedBy;
+                    this.phase = 'Declined';
                 }
-                this.phase = 'Declined';
                 break;
             }
             case 'Commitment': {
@@ -74,6 +157,14 @@ class HandoffProjection {
                 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/proposal.d.ts

@@ -1,3 +1,4 @@
+import type { ProjectionAnomaly } from './base';
 import type { Envelope } from '../types';
 import type { ProtoRegistry } from '../proto-registry';
 export interface ProposalRecord {
@@ -24,17 +25,88 @@ export declare class ProposalProjection {
     readonly proposals: Map<string, ProposalRecord>;
     readonly accepts: ProposalAcceptRecord[];
     readonly rejections: ProposalRejectRecord[];
+    /**
+     * Each sender's current (unsuperseded) `Accept`, keyed by sender.
+     * RFC-MACP-0008 §5 rule 5 (`:70`): "A participant MAY change its
+     * acceptance target by sending a later `Accept` for a different live
+     * proposal. The latest accepted `Accept` from a participant supersedes
+     * earlier accepts from the same participant." `accepts` above retains the
+     * full append-only history (including superseded accepts) for audit
+     * purposes; `isAccepted` and `acceptedProposal` read from this map instead
+     * so they reflect the live acceptance set — required for determinism by
+     * §7 (`:89`): "Given the same accepted history and the same version-bound
+     * rules, implementations MUST derive the same live proposal set, the same
+     * acceptance set, and the same commitment eligibility."
+     */
+    private readonly latestAcceptBySender;
+    /**
+     * 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 Proposal mode.
+     */
+    readonly anomalies: ProjectionAnomaly[];
     phase: 'Negotiating' | 'TerminalRejected' | '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;
     activeProposals(): ProposalRecord[];
     latestProposal(): ProposalRecord | undefined;
+    /**
+     * True if some participant's *current* (unsuperseded) `Accept` targets
+     * `proposalId` — RFC-MACP-0008 §5 rule 5 (`:70`). Note this reads from the
+     * live acceptance set, not from `accepts`' full history: a participant
+     * whose only accept for `proposalId` was later superseded by a re-accept
+     * of a different proposal is not counted.
+     */
     isAccepted(proposalId: string): boolean;
     isTerminallyRejected(proposalId: string): boolean;
     liveProposals(): Map<string, ProposalRecord>;
+    /**
+     * The single proposal every participant's *current* accept targets, or
+     * `undefined` if no one has an outstanding accept or outstanding accepts
+     * are split across more than one proposal. Computed from the live
+     * acceptance set (see `isAccepted`), not from `accepts`' full history — a
+     * participant who accepts `p1` and later re-accepts `p2` (RFC-MACP-0008 §5
+     * rule 5, `:70`) contributes only `p2`, so this correctly returns `p2`
+     * rather than `undefined`.
+     */
     acceptedProposal(): string | undefined;
     hasTerminalRejection(): boolean;
 }