macp-sdk-typescript 0.10.0 → 0.12.0

package/dist/policy.js

@@ -8,27 +8,126 @@ exports.buildHandoffPolicy = buildHandoffPolicy;
 const errors_1 = require("./errors");
 // ── Builder helpers ─────────────────────────────────────────────────
 function serializeCommitment(commitment) {
+    // `authority: 'designated_role'` with an empty (or unset) `designatedRoles`
+    // names no one, so no sender could ever satisfy it. All five rule schemas
+    // reject this combination at admission (spec PR #121) via a root-level
+    // `allOf` conditional arm, not an inline constraint on the property, so it
+    // is easy to miss. Validated once, here, so every mode builder gets it
+    // uniformly -- mirrors python-sdk `_commitment_dict`, policy.py:49-60.
+    //
+    // Explicit length check, not a truthiness test (Python's `not
+    // c.designated_roles`): the omitted-field and supplied-`[]` cases both
+    // collapse to length 0 here, and both must throw -- unlike Phase 3's
+    // weights rule, there is no supplied-vs-absent distinction to preserve.
+    if (commitment?.authority === 'designated_role' && (commitment.designatedRoles?.length ?? 0) === 0) {
+        throw new errors_1.MacpSessionError("commitment.authority is 'designated_role' but designatedRoles is empty -- this names no one, " +
+            'so no sender could ever satisfy it. Pass at least one role/participant id in designatedRoles.');
+    }
     return {
         authority: commitment?.authority ?? 'initiator_only',
         designated_roles: commitment?.designatedRoles ?? [],
-        // Parity with python-sdk `_commitment_dict`: emitted for every mode, not
-        // just decision, so policy JSON is byte-identical across SDKs.
-        require_vote_quorum: commitment?.requireVoteQuorum ?? false,
+        // `require_vote_quorum` and `allow_decline_over_approval` are NOT emitted
+        // here -- the canonical *-rules.schema.json commitment object closes with
+        // `additionalProperties: false` for every mode except Decision (issue
+        // #87 item 1, spec PR #125). Only decision-rules.schema.json's commitment
+        // object lists `require_vote_quorum`/`allow_decline_over_approval` as
+        // known keys; quorum/proposal/task/handoff-rules.schema.json's commitment
+        // object allows only `authority`/`designated_roles`. `buildDecisionPolicy`
+        // adds both fields itself, after calling this helper. Emitting them here
+        // unconditionally (as this SDK and python-sdk's `_commitment_dict` both
+        // used to, for byte-parity with each other rather than with the spec) put
+        // a key the other four modes' schemas do not recognize onto the wire --
+        // inert under today's runtime (which does not enforce
+        // `additionalProperties`) but non-conformant, and a real rejection under
+        // any stricter/future validator.
     };
 }
-function buildDecisionPolicy(policyId, description, rules) {
-    // Decision-only: extend the shared v1 commitment rules with the schema_version 2
-    // decline-over-approval switch, appended after the shared keys so it does not
-    // leak into the still-v1 quorum/proposal/task/handoff commitment blocks
-    // (parity with python-sdk `_commitment_dict` + `build_decision_policy`).
+// Typed against VotingRules['algorithm'] (not a bare string[]) so adding a
+// seventh canonical algorithm to that union without also adding it here is a
+// tsc error instead of a silent runtime-only rejection — same frozen-set
+// intent as this file's other guards (see e.g. commitment-hash-frozen-fields.test.ts).
+const DECISION_ALGORITHMS = new Set([
+    'none',
+    'majority',
+    'supermajority',
+    'unanimous',
+    'weighted',
+    'plurality',
+]);
+// RFC-MACP-0012 §8 requires runtimes to accept all three forever -- none of
+// these is a deprecation path. Mirrors macp-sdk-python policy.py's
+// _DECISION_SCHEMA_VERSIONS.
+const DECISION_SCHEMA_VERSIONS = new Set([1, 2, 3]);
+function buildDecisionPolicy(policyId, description, rules, options) {
+    const schemaVersion = options?.schemaVersion ?? 3;
+    if (!DECISION_SCHEMA_VERSIONS.has(schemaVersion)) {
+        throw new errors_1.MacpSessionError(`schemaVersion must be one of ${[...DECISION_SCHEMA_VERSIONS].sort().join(', ')}, got '${schemaVersion}'`);
+    }
+    const algorithm = rules.voting?.algorithm ?? 'none';
+    const threshold = rules.voting?.threshold ?? 0.5;
+    const weights = rules.voting?.weights;
+    // Match decision-rules.schema.json's constraints before the runtime does,
+    // same rationale as buildQuorumPolicy's threshold checks above: a bad
+    // descriptor fails immediately client-side instead of round-tripping to an
+    // INVALID_POLICY_DEFINITION from RegisterPolicy. Order matters and mirrors
+    // macp-sdk-python policy.py:148-180: algorithm enum, then threshold range,
+    // then the majority/supermajority asymmetry, then weighted-requires-weights,
+    // then the electorate rule (unconditional across every algorithm).
+    if (!DECISION_ALGORITHMS.has(algorithm)) {
+        throw new errors_1.MacpSessionError(`voting algorithm must be one of ${[...DECISION_ALGORITHMS].sort().join(', ')}, got '${algorithm}'`);
+    }
+    if (!(threshold > 0 && threshold <= 1)) {
+        throw new errors_1.MacpSessionError(`voting threshold must be > 0 and <= 1, got ${threshold}`);
+    }
+    if (algorithm === 'majority' && threshold < 0.5) {
+        throw new errors_1.MacpSessionError(`'majority' requires threshold >= 0.5 (an even split approves), got ${threshold}`);
+    }
+    // Deliberately asymmetric with the 'majority' check above: policy.std.majority
+    // sets threshold exactly 0.5 and RFC-MACP-0012 §2.2 pins that reserved profile
+    // byte-identical on every runtime, so an exclusive >= 0.5 bound here would
+    // refuse a profile the runtime pre-registers at startup. Do not "fix" this.
+    if (algorithm === 'supermajority' && threshold <= 0.5) {
+        throw new errors_1.MacpSessionError("'supermajority' requires threshold > 0.5 -- the field's own default of 0.5 is a bare majority " +
+            `wearing the name, got ${threshold}. Pass an explicit threshold (e.g. 0.67) for supermajority.`);
+    }
+    if (algorithm === 'weighted' && (!weights || Object.keys(weights).length === 0)) {
+        throw new errors_1.MacpSessionError("'weighted' algorithm requires a non-empty 'weights' map");
+    }
+    // The weighted electorate is meaningful only when non-empty and strictly
+    // positive-valued -- enforced unconditionally, at every algorithm, not only
+    // 'weighted' (decision-rules.schema.json: voting.weights minProperties 1,
+    // additionalProperties.exclusiveMinimum 0; normative at every schema_version).
+    // A weight-0 participant is expressed by omission from this map, never by an
+    // explicit 0. `weights !== undefined`, not a truthy check: `{}` is truthy.
+    if (weights !== undefined) {
+        if (Object.keys(weights).length === 0) {
+            throw new errors_1.MacpSessionError("'weights', if provided, must be non-empty");
+        }
+        for (const [participant, weight] of Object.entries(weights)) {
+            // weight <= 0 alone would let a NaN weight slip through (NaN <= 0 is
+            // false); the runtime guards this explicitly (registry.rs:596), mirrored
+            // here even though the Python reference does not check it separately.
+            if (weight <= 0 || Number.isNaN(weight)) {
+                throw new errors_1.MacpSessionError(`weights['${participant}'] must be > 0, got ${weight} -- a weight-0 observer is expressed by ` +
+                    'omission from the map, not by an explicit 0');
+            }
+        }
+    }
+    // Decision-only: extend the shared commitment rules with the two keys
+    // decision-rules.schema.json's commitment object allows and the other four
+    // modes' commitment schemas do not -- `require_vote_quorum` and the
+    // schema_version 2 decline-over-approval switch. Appended after the shared
+    // keys so neither leaks into the still-`additionalProperties: false`
+    // quorum/proposal/task/handoff commitment blocks (see serializeCommitment).
     const commitmentSection = serializeCommitment(rules.commitment);
+    commitmentSection.require_vote_quorum = rules.commitment?.requireVoteQuorum ?? false;
     commitmentSection.allow_decline_over_approval = rules.commitment?.allowDeclineOverApproval ?? false;
     const rulesJson = {
         voting: {
-            algorithm: rules.voting?.algorithm ?? 'none',
-            threshold: rules.voting?.threshold ?? 0.5,
+            algorithm,
+            threshold,
             quorum: rules.voting?.quorum ? { type: rules.voting.quorum.type, value: rules.voting.quorum.value } : undefined,
-            weights: rules.voting?.weights ?? undefined,
+            weights,
         },
         objection_handling: {
             critical_severity_vetoes: rules.objectionHandling?.criticalSeverityVetoes ?? false,
@@ -46,22 +145,47 @@ function buildDecisionPolicy(policyId, description, rules) {
         mode: 'macp.mode.decision.v1',
         description,
         rules: JSON.stringify(rulesJson),
-        schemaVersion: 2,
+        schemaVersion,
     };
 }
 function buildQuorumPolicy(policyId, description, rules) {
-    if (rules.threshold?.type === 'percentage') {
-        const v = rules.threshold.value;
-        if (!Number.isInteger(v) || v < 0 || v > 100) {
-            throw new errors_1.MacpSessionError(`quorum percentage threshold must be an integer in [0, 100] (e.g. 75 for 75%), got ${v}. ` +
-                'The runtime computes the approval bar as ceil(value/100 × participants); a fractional value ' +
-                'like 0.75 would round to a ~1% bar.');
+    const threshold = rules.threshold;
+    if (threshold) {
+        // Match the canonical quorum-rules schema's constraints before the runtime
+        // does, so a bad descriptor fails immediately client-side instead of
+        // round-tripping to an INVALID_POLICY_DEFINITION from RegisterPolicy.
+        // Order matters: integer first (a float reaching the range checks below
+        // would compare fine numerically but produce a confusing message), then
+        // > 0, then the percentage-specific <= 100 cap, then type. Mirrors
+        // macp-sdk-python policy.py:278-310.
+        //
+        // Number.isInteger(true) is false in TS, so unlike Python's
+        // isinstance(True, int) trap (policy.py:285-287), no separate bool guard
+        // is needed here.
+        if (!Number.isInteger(threshold.value)) {
+            throw new errors_1.MacpSessionError(`quorum threshold value must be an integer (e.g. 75 for 75%), got ${threshold.value}. ` +
+                "The canonical quorum-rules schema declares 'value' as an integer for every threshold " +
+                'type; a fractional value like 0.75 would produce a schema-invalid descriptor that the ' +
+                'runtime rejects at RegisterPolicy with worse diagnostics.');
+        }
+        if (threshold.value <= 0) {
+            throw new errors_1.MacpSessionError(`quorum threshold value must be > 0, got ${threshold.value}. A zero approval bar is ` +
+                'trivially satisfied by any ballot set, so the canonical quorum-rules schema declares ' +
+                "'value' with exclusiveMinimum 0.");
+        }
+        if (threshold.type === 'percentage' && threshold.value > 100) {
+            throw new errors_1.MacpSessionError(`quorum threshold value must be 1-100 for type 'percentage', got ${threshold.value}`);
+        }
+        if (threshold.type !== 'n_of_m' && threshold.type !== 'percentage') {
+            throw new errors_1.MacpSessionError(`quorum threshold type must be 'n_of_m' or 'percentage', got ${JSON.stringify(threshold.type)}. ` +
+                "'weighted' is reserved -- it was removed from the canonical schema without ever having " +
+                'defined semantics and must not be used.');
         }
     }
     const rulesJson = {
         threshold: {
             type: rules.threshold?.type ?? 'n_of_m',
-            value: rules.threshold?.value ?? 0,
+            value: rules.threshold?.value ?? 1,
         },
         abstention: {
             counts_toward_quorum: rules.abstention?.countsTowardQuorum ?? false,

package/dist/projections/base.d.ts

@@ -4,9 +4,11 @@ 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.
+ * cross-SDK agreement. `duplicate_task_accept`/`settled_handoff` were added
+ * under exactly that agreement (issue #126/#128; `macp-sdk-python` landed its
+ * half in PR #95, merged `32c6437`).
  */
-export type ProjectionAnomalyKind = 'duplicate_vote' | 'duplicate_ballot';
+export type ProjectionAnomalyKind = 'duplicate_vote' | 'duplicate_ballot' | 'duplicate_task_accept' | 'settled_handoff';
 /**
  * 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
@@ -31,7 +33,8 @@ export type ProjectionAnomalyKind = 'duplicate_vote' | 'duplicate_ballot';
  * `macp-sdk-python`). Do not add, rename, or remove a field without
  * cross-SDK agreement.
  *
- * Only `DecisionProjection` and `QuorumProjection` populate this today.
+ * `DecisionProjection`, `QuorumProjection`, `TaskProjection`, and
+ * `HandoffProjection` populate this today.
  */
 export interface ProjectionAnomaly {
     kind: ProjectionAnomalyKind;
@@ -39,7 +42,10 @@ export interface ProjectionAnomaly {
     messageType: string;
     messageId: string;
     sender: string;
-    /** `proposal_id` (Decision) or `request_id` (Quorum) the duplicate targeted. */
+    /**
+     * `proposal_id` (Decision), `request_id` (Quorum), `task_id` (Task), or
+     * `handoff_id` (Handoff) the anomaly targeted.
+     */
     subjectId: string;
     /**
      * Human-readable detail. For a cross-type Quorum duplicate, `messageType`
@@ -48,12 +54,54 @@ export interface ProjectionAnomaly {
      */
     detail: string;
 }
+/**
+ * The four `ProjectionAnomalyKind` values as named constants — all four are
+ * cross-SDK contract, literally pinned by the spec repo's
+ * `schemas/parity/contract.json` (`projection_anomaly.kinds`, `contract_version`
+ * 1.2.0 — `ANOMALY_DUPLICATE_TASK_ACCEPT`/`ANOMALY_SETTLED_HANDOFF` landed there
+ * under issue #126/#128, after this SDK's PR #134 completed the agreement
+ * `macp-sdk-python`'s PR #95 started). `satisfies` links each constant to the
+ * union above at compile time, so a drifted value fails `npm run check` before
+ * it can ever reach `make verify-parity`.
+ */
+export declare const ANOMALY_DUPLICATE_VOTE = "duplicate_vote";
+export declare const ANOMALY_DUPLICATE_BALLOT = "duplicate_ballot";
+export declare const ANOMALY_DUPLICATE_TASK_ACCEPT = "duplicate_task_accept";
+export declare const ANOMALY_SETTLED_HANDOFF = "settled_handoff";
+/**
+ * Runtime field order for `ProjectionAnomaly`, with the same frozen-set
+ * guarantee as `_ProjectionAnomalyFieldSetIsFrozen` above, expressed as a
+ * value rather than only a type. The spec repo's
+ * `schemas/parity/contract.json` (`projection_anomaly.fields`) pins this
+ * field order as a runtime JSON array, so this SDK needs its own runtime
+ * array to assert against it (see `tests/parity/contract.test.ts`).
+ *
+ * **Public, not hidden — corrected during Phase 2's own verification round.**
+ * An earlier revision of this docblock claimed this constant was
+ * "deliberately NOT added to the public barrel," on the (wrong) assumption
+ * that it would follow `canonicalizeCommitmentPayload`'s precedent in
+ * `commitment-hash.ts`. That precedent doesn't transfer: `commitment-hash.ts`
+ * is barrel-exported via a *named* line in `src/index.ts`
+ * (`export { commitmentHash, isCanonicalCommitmentHash } from
+ * './commitment-hash'`), which can omit a name on purpose. This module is
+ * barrel-exported via `src/projections.ts`'s `export * from
+ * './projections/base'` → `src/index.ts`'s `export * from './projections'`
+ * — a wildcard re-export chain has no way to omit one name, so this constant
+ * reaches `dist/index.d.ts` and the runtime `require('macp-sdk-typescript')`
+ * surface regardless of intent (verified: `node -e "require('./dist/index.js')
+ * .PROJECTION_ANOMALY_FIELD_ORDER"` prints the array). This is harmless —
+ * a small readonly string tuple is no more a surface-area risk than
+ * `STANDARD_MODES` — so the fix is documenting reality, not restructuring
+ * the export chain to force exclusion. Phase 3's public-API snapshot
+ * correctly captures this symbol as part of today's real surface.
+ */
+export declare const PROJECTION_ANOMALY_FIELD_ORDER: readonly ["kind", "mode", "messageType", "messageId", "sender", "subjectId", "detail"];
 /**
  * Abstract base for in-process mode-state tracking — parity with python-sdk's
  * `macp_sdk.base_projection.BaseProjection`. Maintains a shared transcript,
  * phase string, and commitment payload; subclasses override `applyMode`
- * to handle mode-specific envelopes. `SessionStart` and `Commitment` are
- * handled here so custom modes get the common lifecycle for free.
+ * to handle mode-specific envelopes. `Commitment` is handled here so custom
+ * modes get the common lifecycle for free.
  */
 export declare abstract class BaseProjection {
     /**
@@ -84,19 +132,28 @@ export declare abstract class BaseProjection {
     /**
      * Cardinality anomalies recorded while replaying this projection's
      * accepted transcript (e.g. a duplicate vote or ballot from the same
-     * sender). See `ProjectionAnomaly`. Empty unless a subclass calls
-     * `recordAnomaly`. NOTE: as of this SDK's built-in modes, nothing calls
-     * `recordAnomaly` — `DecisionProjection` and `QuorumProjection` do not
-     * extend `BaseProjection` (see the class docblock) and inline their own
-     * two lines instead. This field and `recordAnomaly` exist for ext-mode
-     * `BaseProjection` subclasses outside this repo.
+     * sender, a duplicate `TaskAccept` competing for an already-held assignee
+     * slot, or a `HandoffAccept`/`HandoffDecline` for an already-settled
+     * handoff). See `ProjectionAnomaly`. Empty unless a subclass calls
+     * `recordAnomaly`. **Corrected 2026-09-25** (this note previously said
+     * nothing calls `recordAnomaly` because `DecisionProjection`/
+     * `QuorumProjection` didn't extend `BaseProjection` — that was true before
+     * issue #91's refactor, and is stale now): both `DecisionProjection`
+     * (`decision.ts`) and `QuorumProjection` (`quorum.ts`) extend
+     * `BaseProjection` today and DO call the inherited `recordAnomaly` when
+     * they discard a duplicate vote/ballot — they just pass a literal
+     * `'duplicate_vote'`/`'duplicate_ballot'` string for `kind` rather than
+     * this file's `ANOMALY_DUPLICATE_VOTE`/`ANOMALY_DUPLICATE_BALLOT`
+     * constants (referencing those constants instead is optional cleanup, not
+     * required by anything in this repo). This field and `recordAnomaly` are
+     * no longer ext-mode-only — any subclass, built-in or ext-mode, uses them.
      */
     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
+     * projection observed and discarded a cardinality anomaly (see `anomalies`
+     * above for the full set of kinds). This getter is exactly
      * `anomalies.length > 0`; it never asserts "this transcript violates the
      * spec" (see `ProjectionAnomaly`'s docblock, and `applyEnvelope`'s "Input
      * contract: accepted-only" section above, for why a projection cannot make

package/dist/projections/base.js

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

package/dist/projections/decision.d.ts

@@ -1,4 +1,4 @@
-import type { ProjectionAnomaly } from './base';
+import { BaseProjection } from './base';
 import type { Envelope } from '../types';
 import type { ProtoRegistry } from '../proto-registry';
 export interface DecisionProposalRecord {
@@ -26,59 +26,15 @@ export interface DecisionVoteRecord {
     reason?: string;
     sender: string;
 }
-export declare class DecisionProjection {
+export declare class DecisionProjection extends BaseProjection {
+    protected readonly mode = "macp.mode.decision.v1";
     readonly proposals: Map<string, DecisionProposalRecord>;
     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;
+    /** Handle a Decision-mode envelope. See `BaseProjection.applyEnvelope` for the accepted-only input contract and redelivery/rollback semantics shared by all built-in modes. */
+    protected applyMode(envelope: Envelope, protoRegistry: ProtoRegistry): void;
     voteTotals(): Record<string, number>;
     majorityWinner(): string | undefined;
     /** Returns the APPROVE vote ratio excluding ABSTAIN votes from the denominator. */