macp-sdk-typescript 0.11.0 → 0.12.0

package/dist/client.js

@@ -47,8 +47,10 @@ const path = __importStar(require("node:path"));
 const grpc = __importStar(require("@grpc/grpc-js"));
 const protoLoader = __importStar(require("@grpc/proto-loader"));
 const auth_1 = require("./auth");
+const constants_1 = require("./constants");
 const envelope_1 = require("./envelope");
 const errors_1 = require("./errors");
+const logging_1 = require("./logging");
 const proto_registry_1 = require("./proto-registry");
 const validation_1 = require("./validation");
 class AsyncQueue {
@@ -110,6 +112,26 @@ function grpcStatusName(code) {
     const name = grpc.status[code];
     return typeof name === 'string' ? name : undefined;
 }
+/**
+ * Shared by the five registry-mutation RPCs (issue #107, Python's
+ * `_map_registry_mutation_error`, `client.py:347-362`): a `FAILED_PRECONDITION`
+ * against a read-only registry is a rejection of the *call*, not a transport
+ * fault — surface it as `MacpAckError`, not `MacpTransportError`.
+ */
+const REGISTRY_MUTATION_ACK_STATUSES = { FAILED_PRECONDITION: 'FAILED_PRECONDITION' };
+/**
+ * Convert `grpc.ServiceError.metadata` (a `grpc.Metadata` instance) into the
+ * plain `{ key, value }[]` shape {@link MacpAckError}'s constructor expects.
+ * `Metadata.getMap()` returns `-bin`-suffixed keys as `Buffer` and all other
+ * keys as `string` — exactly the union `MacpAckError.grpcMetadata` declares.
+ * Returns `undefined` when the error carries no metadata (e.g. a
+ * locally-raised error never sent over the wire).
+ */
+function grpcMetadataEntries(metadata) {
+    if (!metadata)
+        return undefined;
+    return Object.entries(metadata.getMap()).map(([key, value]) => ({ key, value }));
+}
 const TIMEOUT = Symbol('stream-read-timeout');
 const STREAM_END = Symbol('stream-end');
 class MacpStream {
@@ -120,15 +142,23 @@ class MacpStream {
     constructor(call) {
         this.call = call;
         call.on('data', (chunk) => {
-            // Support both old format (chunk.envelope) and new oneof format (chunk.response.envelope)
-            const envelope = chunk?.response?.envelope ?? chunk?.envelope;
+            // `StreamSessionResponse.response` is a proto3 `oneof` (envelope | error).
+            // Under this file's own proto-loader options (`oneofs: true`), the
+            // decoded object exposes the payload directly as `chunk.envelope` /
+            // `chunk.error`, with `chunk.response` set to the oneof's ARM NAME as a
+            // *string* (`'envelope'` or `'error'`) — verified against a real
+            // StreamSessionResponse encode/decode roundtrip. So `chunk.response.error`
+            // indexes a string and is always `undefined`; it never matched a real
+            // decoded frame, which is why inline errors were silently dropped.
+            const envelope = chunk?.envelope;
             if (envelope) {
                 this.queue.push(envelope);
             }
-            else if (chunk?.response?.error) {
-                // Inline application-level error — stream stays open
+            else if (chunk?.error) {
+                // Inline application-level error — stream stays open (core.proto).
+                logging_1.logger.warn('inline stream error', { code: chunk.error.code, message: chunk.error.message });
                 for (const cb of this.inlineErrorCallbacks)
-                    cb(chunk.response.error);
+                    cb(chunk.error);
             }
         });
         call.on('error', (error) => {
@@ -288,13 +318,22 @@ class MacpClient {
         const resolved = deadlineMs ?? this.defaultDeadlineMs;
         return resolved ? new Date(Date.now() + resolved) : undefined;
     }
-    unary(method, request, auth, deadlineMs) {
+    unary(method, request, auth, deadlineMs, ackStatuses) {
         return new Promise((resolve, reject) => {
             const callback = (error, response) => {
-                if (error)
-                    reject(new errors_1.MacpTransportError(error.details || error.message, grpcStatusName(error.code)));
-                else
+                if (error) {
+                    const statusName = grpcStatusName(error.code);
+                    const mappedCode = statusName ? ackStatuses?.[statusName] : undefined;
+                    if (mappedCode) {
+                        reject(new errors_1.MacpAckError({ ok: false, error: { code: mappedCode, message: error.details || error.message } }, grpcMetadataEntries(error.metadata)));
+                    }
+                    else {
+                        reject(new errors_1.MacpTransportError(error.details || error.message, statusName));
+                    }
+                }
+                else {
                     resolve(response);
+                }
             };
             const deadline = this.deadline(deadlineMs);
             const metadata = this.metadata(auth);
@@ -332,7 +371,11 @@ class MacpClient {
     }
     async send(envelope, options) {
         const auth = this.requireAuth(options?.auth);
-        const response = await this.unary('Send', { envelope }, auth, options?.deadlineMs);
+        const response = await this.unary('Send', { envelope }, auth, options?.deadlineMs, 
+        // gRPC ALREADY_EXISTS/FAILED_PRECONDITION on Send are application-level
+        // rejections the runtime couldn't express as a normal NACK (issue #107);
+        // surface them as MacpAckError, matching macp-sdk-python (client.py:442-452).
+        { ALREADY_EXISTS: constants_1.SESSION_ALREADY_EXISTS, FAILED_PRECONDITION: constants_1.POLICY_DENIED });
         const ack = response.ack;
         // Duplicate acks are success — the message was already accepted
         if (ack?.duplicate)
@@ -428,23 +471,23 @@ class MacpClient {
                 'a mode without a terminal Commitment can never resolve and the runtime rejects it.');
         }
         const auth = this.requireAuth(options?.auth);
-        return this.unary('RegisterExtMode', { modeDescriptor: descriptor }, auth, options?.deadlineMs);
+        return this.unary('RegisterExtMode', { modeDescriptor: descriptor }, auth, options?.deadlineMs, REGISTRY_MUTATION_ACK_STATUSES);
     }
     async unregisterExtMode(mode, options) {
         const auth = this.requireAuth(options?.auth);
-        return this.unary('UnregisterExtMode', { mode }, auth, options?.deadlineMs);
+        return this.unary('UnregisterExtMode', { mode }, auth, options?.deadlineMs, REGISTRY_MUTATION_ACK_STATUSES);
     }
     async promoteMode(mode, promotedModeName = '', options) {
         const auth = this.requireAuth(options?.auth);
-        return this.unary('PromoteMode', { mode, promotedModeName }, auth, options?.deadlineMs);
+        return this.unary('PromoteMode', { mode, promotedModeName }, auth, options?.deadlineMs, REGISTRY_MUTATION_ACK_STATUSES);
     }
     async registerPolicy(descriptor, options) {
         const auth = this.requireAuth(options?.auth);
-        return this.unary('RegisterPolicy', { policyDescriptor: descriptor }, auth, options?.deadlineMs);
+        return this.unary('RegisterPolicy', { policyDescriptor: descriptor }, auth, options?.deadlineMs, REGISTRY_MUTATION_ACK_STATUSES);
     }
     async unregisterPolicy(policyId, options) {
         const auth = this.requireAuth(options?.auth);
-        return this.unary('UnregisterPolicy', { policyId }, auth, options?.deadlineMs);
+        return this.unary('UnregisterPolicy', { policyId }, auth, options?.deadlineMs, REGISTRY_MUTATION_ACK_STATUSES);
     }
     async getPolicy(policyId, options) {
         const auth = this.requireAuth(options?.auth);

package/dist/commitment-hash.d.ts

@@ -14,9 +14,24 @@ import type { CommitmentPayload } from './types';
  * that is locale-sensitive and not equivalent to code-unit ordering; it is
  * moot only because the names above are already in the right order.
  *
- * `supersedes` is omitted entirely when `payload.supersedes === undefined`
- * (D2.3) — including when the payload itself is missing/malformed, `payload
- * ?? {}` never manufactures a `supersedes` key. An explicit
+ * `supersedes` is omitted entirely when `payload.supersedes` is `undefined`
+ * OR `null` (D2.3) — including when the payload itself is missing/malformed,
+ * `payload ?? {}` never manufactures a `supersedes` key. `supersedes` is a
+ * proto3 optional/message-typed field: its only two wire states are present
+ * and absent, and `null` is the idiomatic in-language representation of
+ * "absent" for a message-typed field (e.g. under a `defaults: true`
+ * protobufjs/proto-loader decode, or a payload round-tripped through JSON).
+ * The comparison below is deliberately `!= null` (loose), not `!==
+ * undefined` — do not tighten it back; that would resurrect issue #105,
+ * where a `null` `supersedes` hashed as present-but-empty instead of absent,
+ * diverging from `macp-sdk-python`'s `HasField`-based projection for the
+ * same logical commitment. This is deliberately more tolerant than
+ * `buildCommitmentPayload` (`envelope.ts`), which still throws on an
+ * explicit `supersedes: null` — that function validates a caller's stated
+ * intent and should reject a likely mistake; this one (D3) must tolerate
+ * whatever a `CommitmentPayload` from any source already contains,
+ * including a `null` that is a legitimate "absent" from elsewhere (e.g. a
+ * `defaults: true` decode). The two are not meant to converge. An explicit
  * `supersedes: { sessionId: '', commitmentHash: '' }` is NOT collapsed into
  * omission; it is present with two empty-string members, `commitment_hash`
  * before `session_id` (also alphabetical).
@@ -39,3 +54,18 @@ export declare function canonicalizeCommitmentPayload(payload: CommitmentPayload
  * failure rather than being silently swallowed by a catch-all.
  */
 export declare function commitmentHash(payload: CommitmentPayload): string;
+/**
+ * The same shape `commitmentHash` always produces: `sha256:` followed by 64
+ * lowercase hex digits. Non-throwing counterpart to `validateCommitmentHash`
+ * (`src/validation.ts`, which throws `MacpSessionError` on mismatch) — use
+ * this predicate where a boolean fits better than a thrown exception, e.g.
+ * filtering a list or a non-fatal check. Both share one regex family
+ * (`/^sha256:[0-9a-f]{64}$/`); keep them in sync if either changes.
+ *
+ * Never throws, for any input. `$` without the `m` flag anchors to the
+ * absolute end of the string (not "before a trailing newline", unlike some
+ * regex engines) — so a trailing `\n` after an otherwise-valid hash already
+ * fails to match with no special-casing needed, matching Python's
+ * `fullmatch` semantics for this pattern.
+ */
+export declare function isCanonicalCommitmentHash(value: string): boolean;

package/dist/commitment-hash.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.canonicalizeCommitmentPayload = canonicalizeCommitmentPayload;
 exports.commitmentHash = commitmentHash;
+exports.isCanonicalCommitmentHash = isCanonicalCommitmentHash;
 /**
  * RFC-MACP-0013 canonical commitment hashing.
  *
@@ -141,9 +142,24 @@ function jcsBoolean(value) {
  * that is locale-sensitive and not equivalent to code-unit ordering; it is
  * moot only because the names above are already in the right order.
  *
- * `supersedes` is omitted entirely when `payload.supersedes === undefined`
- * (D2.3) — including when the payload itself is missing/malformed, `payload
- * ?? {}` never manufactures a `supersedes` key. An explicit
+ * `supersedes` is omitted entirely when `payload.supersedes` is `undefined`
+ * OR `null` (D2.3) — including when the payload itself is missing/malformed,
+ * `payload ?? {}` never manufactures a `supersedes` key. `supersedes` is a
+ * proto3 optional/message-typed field: its only two wire states are present
+ * and absent, and `null` is the idiomatic in-language representation of
+ * "absent" for a message-typed field (e.g. under a `defaults: true`
+ * protobufjs/proto-loader decode, or a payload round-tripped through JSON).
+ * The comparison below is deliberately `!= null` (loose), not `!==
+ * undefined` — do not tighten it back; that would resurrect issue #105,
+ * where a `null` `supersedes` hashed as present-but-empty instead of absent,
+ * diverging from `macp-sdk-python`'s `HasField`-based projection for the
+ * same logical commitment. This is deliberately more tolerant than
+ * `buildCommitmentPayload` (`envelope.ts`), which still throws on an
+ * explicit `supersedes: null` — that function validates a caller's stated
+ * intent and should reject a likely mistake; this one (D3) must tolerate
+ * whatever a `CommitmentPayload` from any source already contains,
+ * including a `null` that is a legitimate "absent" from elsewhere (e.g. a
+ * `defaults: true` decode). The two are not meant to converge. An explicit
  * `supersedes: { sessionId: '', commitmentHash: '' }` is NOT collapsed into
  * omission; it is present with two empty-string members, `commitment_hash`
  * before `session_id` (also alphabetical).
@@ -167,9 +183,10 @@ function canonicalizeCommitmentPayload(payload) {
         `"policy_version":${jcsString(p.policyVersion ?? '')}`,
         `"reason":${jcsString(p.reason)}`,
     ];
-    if (p.supersedes !== undefined) {
+    if (p.supersedes != null) {
         // Optional chaining tolerates `supersedes` being present but not
-        // actually an object (null, a primitive, ...) on a malformed payload —
+        // actually an object (a primitive: `5`, `'x'`, `true`, ... — `null` is
+        // excluded above, it never reaches this branch) on a malformed payload —
         // it never throws, it just yields `undefined` for the sub-fields, which
         // `jcsString` then coerces to `""` the same way it handles any other
         // missing string field.
@@ -196,3 +213,20 @@ function commitmentHash(payload) {
     const digest = (0, node_crypto_1.createHash)('sha256').update(Buffer.from(preimage, 'utf8')).digest('hex');
     return `sha256:${digest}`;
 }
+/**
+ * The same shape `commitmentHash` always produces: `sha256:` followed by 64
+ * lowercase hex digits. Non-throwing counterpart to `validateCommitmentHash`
+ * (`src/validation.ts`, which throws `MacpSessionError` on mismatch) — use
+ * this predicate where a boolean fits better than a thrown exception, e.g.
+ * filtering a list or a non-fatal check. Both share one regex family
+ * (`/^sha256:[0-9a-f]{64}$/`); keep them in sync if either changes.
+ *
+ * Never throws, for any input. `$` without the `m` flag anchors to the
+ * absolute end of the string (not "before a trailing newline", unlike some
+ * regex engines) — so a trailing `\n` after an otherwise-valid hash already
+ * fails to match with no special-casing needed, matching Python's
+ * `fullmatch` semantics for this pattern.
+ */
+function isCanonicalCommitmentHash(value) {
+    return /^sha256:[0-9a-f]{64}$/.test(value);
+}

package/dist/decision.d.ts

@@ -32,6 +32,7 @@ export declare class DecisionSession {
         }[];
         maxSuspendMs?: number;
         sender?: string;
+        auth?: AuthConfig;
     }): Promise<Ack>;
     propose(input: DecisionProposalPayload & {
         sender?: string;

package/dist/decision.js

@@ -60,10 +60,10 @@ class DecisionSession {
             mode: constants_1.MODE_DECISION,
             messageType: 'SessionStart',
             sessionId: this.sessionId,
-            sender: this.senderFor(input.sender),
+            sender: this.senderFor(input.sender, input.auth),
             payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_DECISION, 'SessionStart', (0, envelope_1.toProtoPayload)(payload)),
         });
-        return this.sendAndTrack(envelope, this.auth);
+        return this.sendAndTrack(envelope, input.auth ?? this.auth);
     }
     async propose(input) {
         (0, validation_1.validateRequiredField)('proposalId', input.proposalId);
@@ -79,39 +79,41 @@ class DecisionSession {
     }
     async evaluate(input) {
         (0, validation_1.validateRequiredField)('proposalId', input.proposalId);
-        (0, validation_1.validateRecommendation)(input.recommendation);
+        // Use the validators' returned normalized values (issue #108.3) — they
+        // return a normalized string precisely so callers put the wire-canonical
+        // form on the envelope, not whatever case the caller happened to pass.
+        const recommendation = (0, validation_1.validateRecommendation)(input.recommendation);
         (0, validation_1.validateConfidence)(input.confidence);
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_DECISION,
             messageType: 'Evaluation',
             sessionId: this.sessionId,
             sender: this.senderFor(input.sender, input.auth),
-            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_DECISION, 'Evaluation', (0, envelope_1.toProtoPayload)(input)),
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_DECISION, 'Evaluation', (0, envelope_1.toProtoPayload)({ ...input, recommendation })),
         });
         return this.sendAndTrack(envelope, input.auth);
     }
     async raiseObjection(input) {
         (0, validation_1.validateRequiredField)('proposalId', input.proposalId);
-        if (input.severity)
-            (0, validation_1.validateSeverity)(input.severity);
+        const severity = input.severity ? (0, validation_1.validateSeverity)(input.severity) : input.severity;
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_DECISION,
             messageType: 'Objection',
             sessionId: this.sessionId,
             sender: this.senderFor(input.sender, input.auth),
-            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_DECISION, 'Objection', (0, envelope_1.toProtoPayload)(input)),
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_DECISION, 'Objection', (0, envelope_1.toProtoPayload)({ ...input, severity })),
         });
         return this.sendAndTrack(envelope, input.auth);
     }
     async vote(input) {
         (0, validation_1.validateRequiredField)('proposalId', input.proposalId);
-        (0, validation_1.validateVote)(input.vote);
+        const vote = (0, validation_1.validateVote)(input.vote);
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_DECISION,
             messageType: 'Vote',
             sessionId: this.sessionId,
             sender: this.senderFor(input.sender, input.auth),
-            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_DECISION, 'Vote', (0, envelope_1.toProtoPayload)(input)),
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_DECISION, 'Vote', (0, envelope_1.toProtoPayload)({ ...input, vote })),
         });
         return this.sendAndTrack(envelope, input.auth);
     }

package/dist/envelope.js

@@ -92,7 +92,15 @@ function buildCommitmentPayload(input) {
         if (typeof input.supersedes !== 'object' || input.supersedes === null) {
             // `String()`, not `JSON.stringify()`: the latter throws on a bigint,
             // which would replace this deliberate `MacpSessionError` with an
-            // unrelated `TypeError` for that one input shape.
+            // unrelated `TypeError` for that one input shape. Deliberately
+            // stricter here than `commitmentHash`'s D3 "never throw" contract
+            // (issue #105): this is a constructor validating a caller's own
+            // explicit intent, not a hasher that must tolerate any
+            // already-materialized `CommitmentPayload` from any source (including
+            // one decoded elsewhere with `defaults: true`, where a `null` is a
+            // legitimate "absent" reaching the hasher, not a mistake reaching the
+            // builder) — so a `null` here throws instead of being silently
+            // treated as absent.
             throw new errors_1.MacpSessionError(`supersedes must be a CommitmentRef object, got: ${String(input.supersedes)}`);
         }
         (0, validation_1.validateCommitmentHash)(input.supersedes.commitmentHash);

package/dist/handoff.d.ts

@@ -32,6 +32,7 @@ export declare class HandoffSession {
         }[];
         maxSuspendMs?: number;
         sender?: string;
+        auth?: AuthConfig;
     }): Promise<Ack>;
     offer(input: HandoffOfferPayload & {
         sender?: string;

package/dist/handoff.js

@@ -60,10 +60,10 @@ class HandoffSession {
             mode: constants_1.MODE_HANDOFF,
             messageType: 'SessionStart',
             sessionId: this.sessionId,
-            sender: this.senderFor(input.sender),
+            sender: this.senderFor(input.sender, input.auth),
             payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_HANDOFF, 'SessionStart', (0, envelope_1.toProtoPayload)(payload)),
         });
-        return this.sendAndTrack(envelope, this.auth);
+        return this.sendAndTrack(envelope, input.auth ?? this.auth);
     }
     async offer(input) {
         (0, validation_1.validateRequiredField)('handoffId', input.handoffId);
@@ -80,40 +80,53 @@ class HandoffSession {
     }
     async addContext(input) {
         (0, validation_1.validateRequiredField)('handoffId', input.handoffId);
+        // Issue #108.6/4f: default contentType, matching Python (`handoff.py:210`).
+        // Deliberately `||`, not the `??` `offer()` above uses for `scope`: an
+        // explicit empty string must also fall back to the default here.
+        const contextInput = { ...input, contentType: input.contentType || 'application/octet-stream' };
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_HANDOFF,
             messageType: 'HandoffContext',
             sessionId: this.sessionId,
             sender: this.senderFor(input.sender, input.auth),
-            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_HANDOFF, 'HandoffContext', (0, envelope_1.toProtoPayload)(input)),
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_HANDOFF, 'HandoffContext', (0, envelope_1.toProtoPayload)(contextInput)),
         });
         return this.sendAndTrack(envelope, input.auth);
     }
     async acceptHandoff(input) {
         (0, validation_1.validateRequiredField)('handoffId', input.handoffId);
+        const sender = this.senderFor(input.sender, input.auth);
         // `implicit` is a runtime-emitted-only flag (RFC-MACP-0010 §5.1); the
         // runtime rejects client-submitted accepts with implicit=true. Strip it so
         // a caller can never produce a rejected envelope, regardless of what they
         // pass — belt and braces with the JSDoc "read-only" contract on the type.
         const rest = { ...input };
         delete rest.implicit;
+        // Issue #108.5/4e: default acceptedBy to the resolved sender. Applied to
+        // `rest` (the object actually encoded below), NOT to `input` — unlike
+        // every other action here, this method doesn't route through
+        // `toProtoPayload(input)`, so a fallback written against `input` would be
+        // silently dropped.
+        rest.acceptedBy = input.acceptedBy || sender;
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_HANDOFF,
             messageType: 'HandoffAccept',
             sessionId: this.sessionId,
-            sender: this.senderFor(input.sender, input.auth),
+            sender,
             payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_HANDOFF, 'HandoffAccept', rest),
         });
         return this.sendAndTrack(envelope, input.auth);
     }
     async decline(input) {
         (0, validation_1.validateRequiredField)('handoffId', input.handoffId);
+        const sender = this.senderFor(input.sender, input.auth);
+        const declinedBy = input.declinedBy || sender;
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_HANDOFF,
             messageType: 'HandoffDecline',
             sessionId: this.sessionId,
-            sender: this.senderFor(input.sender, input.auth),
-            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_HANDOFF, 'HandoffDecline', (0, envelope_1.toProtoPayload)(input)),
+            sender,
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_HANDOFF, 'HandoffDecline', (0, envelope_1.toProtoPayload)({ ...input, declinedBy })),
         });
         return this.sendAndTrack(envelope, input.auth);
     }

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 export { Auth, type AuthConfig, type BearerAuthOptions } from './auth';
 export * from './base-session';
 export * from './client';
-export { commitmentHash } from './commitment-hash';
+export { commitmentHash, isCanonicalCommitmentHash } from './commitment-hash';
 export * from './constants';
 export * from './decision';
 export * from './envelope';
 export * from './errors';
 export * from './handoff';
-export * from './logging';
+export { configureLogging, logger, type LogLevel, type LogSink } from './logging';
 export * from './policy';
 export * from './projections';
 export * from './proposal';

package/dist/index.js

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.agent = exports.VERSION = exports.commitmentHash = exports.Auth = void 0;
+exports.agent = exports.VERSION = exports.logger = exports.configureLogging = exports.isCanonicalCommitmentHash = exports.commitmentHash = exports.Auth = void 0;
 // Auth: export only the public constructors and types. The helpers
 // `validateAuth`, `authSender`, `assertSenderMatchesIdentity`, and
 // `metadataFromAuth` are SDK-internal — importable from the `./auth`
@@ -46,19 +46,30 @@ var auth_1 = require("./auth");
 Object.defineProperty(exports, "Auth", { enumerable: true, get: function () { return auth_1.Auth; } });
 __exportStar(require("./base-session"), exports);
 __exportStar(require("./client"), exports);
-// Commitment hash: export only `commitmentHash`. `canonicalizeCommitmentPayload`
-// is the projection/JCS half of the algorithm — importable from the
-// `./commitment-hash` submodule (as the vector-runner tests do) but kept off
-// the top-level surface to match python-sdk's public API, which does not
-// expose its `canonical_projection` equivalent either.
+// Commitment hash: export `commitmentHash` and `isCanonicalCommitmentHash`.
+// `canonicalizeCommitmentPayload` is the projection/JCS half of the
+// algorithm — importable from the `./commitment-hash` submodule (as the
+// vector-runner tests do) but kept off the top-level surface to match
+// python-sdk's public API, which does not expose its `canonical_projection`
+// equivalent either.
 var commitment_hash_1 = require("./commitment-hash");
 Object.defineProperty(exports, "commitmentHash", { enumerable: true, get: function () { return commitment_hash_1.commitmentHash; } });
+Object.defineProperty(exports, "isCanonicalCommitmentHash", { enumerable: true, get: function () { return commitment_hash_1.isCanonicalCommitmentHash; } });
 __exportStar(require("./constants"), exports);
 __exportStar(require("./decision"), exports);
 __exportStar(require("./envelope"), exports);
 __exportStar(require("./errors"), exports);
 __exportStar(require("./handoff"), exports);
-__exportStar(require("./logging"), exports);
+// Logging: export the public surface only. `_resetLoggingForTests` is a
+// test-only reset helper — excluded here (a one-hop wildcard, unlike
+// `PROJECTION_ANOMALY_FIELD_ORDER`'s two-hop chain via `./projections`,
+// which cannot be excluded this way). `package.json`'s `exports` map
+// exposes only `.`, so this makes it unreachable from the published
+// package, not merely un-barrelled — accepted, since it is test-only by
+// name and by purpose.
+var logging_1 = require("./logging");
+Object.defineProperty(exports, "configureLogging", { enumerable: true, get: function () { return logging_1.configureLogging; } });
+Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return logging_1.logger; } });
 __exportStar(require("./policy"), exports);
 __exportStar(require("./projections"), exports);
 __exportStar(require("./proposal"), exports);

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