macp-sdk-typescript 0.10.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/policy.d.ts

@@ -1,8 +1,22 @@
 import type { PolicyDescriptor } from './types';
 export interface CommitmentRules {
     authority?: 'initiator_only' | 'any_participant' | 'designated_role';
+    /**
+     * Required non-empty when `authority` is `'designated_role'` — every
+     * builder throws `MacpSessionError` otherwise, since an authority rule
+     * naming no one is unsatisfiable. Ignored (serialized but inert) under the
+     * other two authorities.
+     */
     designatedRoles?: string[];
-    /** Decision-specific: require quorum before commit. Ignored for other modes. */
+    /**
+     * Decision-specific: require quorum before commit. Emitted only by
+     * `buildDecisionPolicy` (matching `decision-rules.schema.json`'s
+     * commitment object, the only one of the five that declares this key) —
+     * silently dropped, not merely ignored, when passed to the other four
+     * builders, so the still-`additionalProperties: false`
+     * quorum/proposal/task/handoff commitment schemas are unaffected (issue
+     * #87 item 1).
+     */
     requireVoteQuorum?: boolean;
     /**
      * RFC-MACP-0012 schema_version 2, Decision mode only: when `true`, a
@@ -49,15 +63,20 @@ export interface EvaluationRules {
     requiredBeforeVoting?: boolean;
 }
 export interface QuorumThreshold {
-    type: 'n_of_m' | 'percentage' | 'weighted';
+    type: 'n_of_m' | 'percentage';
     /**
      * The approval bar (RFC-MACP-0012 §4.2) — how many APPROVE commitments the
      * request needs, NOT a participation quorum. Scale depends on `type`:
-     * - `n_of_m` / `weighted`: an absolute count (or weight sum).
-     * - `percentage`: an **integer 0–100**; the runtime computes the bar as
+     * - `n_of_m`: an absolute count.
+     * - `percentage`: an **integer 1–100**; the runtime computes the bar as
      *   `ceil(value / 100 × participants)`. So `75` means "≥ 75% of participants
-     *   must approve", NOT `0.75`. `buildQuorumPolicy` validates this range and
-     *   throws on a non-integer or out-of-[0,100] value.
+     *   must approve", NOT `0.75`.
+     *
+     * Must be a **positive integer** for every `type` (`exclusiveMinimum: 0` in
+     * the canonical `quorum-rules.schema.json`, unconditional — a zero approval
+     * bar would be trivially satisfied by any ballot set). `buildQuorumPolicy`
+     * validates this and throws on a non-integer, non-positive, or (for
+     * `percentage`) out-of-[1,100] value.
      */
     value: number;
 }
@@ -109,7 +128,35 @@ export interface HandoffPolicyRulesInput {
     acceptance?: HandoffAcceptanceRules;
     commitment?: CommitmentRules;
 }
-export declare function buildDecisionPolicy(policyId: string, description: string, rules: DecisionPolicyRulesInput): PolicyDescriptor;
+export interface DecisionPolicyOptions {
+    /**
+     * RFC-MACP-0012 rule schema version the runtime evaluates this policy
+     * under (validated, never re-validated, at admission -- RFC-MACP-0012 §8
+     * item 4):
+     * - `1`/`2`: an empty decisive tally is fail-*open* (satisfies the voting
+     *   requirement).
+     * - `3`: an empty decisive tally is fail-*closed* for every algorithm
+     *   except `'none'` (RFC-MACP-0012 §4.1, adopted in spec PR #99).
+     *
+     * Defaults to `3` (issue #85, decided jointly with `macp-sdk-python`'s
+     * identical `schema_version: int = 3` default -- see that repo's issue
+     * #65): RFC-MACP-0012's authoring guidance is that new non-`'none'`
+     * policies SHOULD declare `schemaVersion: 3`, and the old default of `2`
+     * was fail-*open* on an empty tally for exactly the callers who opted into
+     * a binding algorithm (`majority`, `unanimous`, etc.) -- silently
+     * satisfying a vote that received zero ballots, which contradicts what
+     * asking for a binding algorithm means. RFC-MACP-0012 §8 makes the choice
+     * reversible and non-retroactive: a stored policy always evaluates under
+     * its own declared version forever, so this default change carries no
+     * migration risk for existing registered policies -- it only changes what
+     * new callers who don't pass `schemaVersion` explicitly get going forward.
+     * Pass `1` or `2` explicitly to keep fail-open empty-tally semantics. This
+     * is descriptor metadata, not a rule: it is never part of the serialized
+     * `rules` JSON.
+     */
+    schemaVersion?: 1 | 2 | 3;
+}
+export declare function buildDecisionPolicy(policyId: string, description: string, rules: DecisionPolicyRulesInput, options?: DecisionPolicyOptions): PolicyDescriptor;
 export declare function buildQuorumPolicy(policyId: string, description: string, rules: QuorumPolicyRulesInput): PolicyDescriptor;
 export declare function buildProposalPolicy(policyId: string, description: string, rules: ProposalPolicyRulesInput): PolicyDescriptor;
 export declare function buildTaskPolicy(policyId: string, description: string, rules: TaskPolicyRulesInput): PolicyDescriptor;