macp-sdk-typescript 0.14.1 → 0.16.0

package/CHANGELOG.md

@@ -4,14 +4,28 @@ All notable changes to `macp-sdk-typescript` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 project uses [Semantic Versioning](https://semver.org/).
 
-## [0.14.1](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.14.0...v0.14.1) (2026-10-03)
+## [0.16.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.15.0...v0.16.0) (2026-10-18)
+
+
+### Features
+
+* **watchers:** SignalWatcher.events() surfaces sender_authenticated (runtime 0.9.0) ([#172](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/172)) ([57491cd](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/57491cd8e156c9f1650a918e36eea5ff9d2bdab1))
+
+## [0.15.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.14.1...v0.15.0) (2026-10-17)
+
+
+### Features
+
+* **commitment-hash:** RFC-MACP-0013 §6.1 verifyCommitmentHash + verify vectors 006–010 ([#170](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/170)) ([a39421c](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/a39421cfb2908731b1470ff787b0fffcacfd6299))
+* **errors:** export DENY_* constants and KNOWN_DENY_CODES; keep message-less denials ([#169](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/169)) ([fef7335](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/fef733589427dd185fe445024e330c8c10d4c864)), closes [#168](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/168)
+* **errors:** runtime 0.9.0 registry error codes and structured policy denials ([#164](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/164)) ([d37ad7f](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/d37ad7ff799e94b66271a08e7d18774b115d1c4c))
 
 
 ### Bug Fixes
 
-* **parity:** re-vendor contract.json for contract_version 1.3.0 ([#156](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/156)) ([#157](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/157)) ([497949d](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/497949d2b29031d340f5d8cc2ef17ae34c946c42))
+* **validation:** cap base64url session ids at 128 bytes ([#167](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/167)) ([bb60588](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/bb60588f67edcb200e9f109491e3a262232a8a11))
 
-## [Unreleased]
+## [0.14.1](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.14.0...v0.14.1) (2026-10-03)
 
 ### Added
 
@@ -72,6 +86,7 @@ project uses [Semantic Versioning](https://semver.org/).
   covers a cleanly-ended watch stream alongside every other SDK failure.
   Message strings are unchanged byte-for-byte; `error.code` remains
   `undefined` on all 5 (locally raised, no gRPC status to attach).
+- **parity:** re-vendor contract.json for contract_version 1.3.0 ([#156](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/156)) ([#157](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/157)) ([497949d](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/497949d2b29031d340f5d8cc2ef17ae34c946c42))
 
 ## [0.14.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.13.0...v0.14.0) (2026-10-01)
 

package/README.md

@@ -43,7 +43,9 @@ await client.initialize();
 const session = new DecisionSession(client);
 await session.start({
   intent: 'pick a deployment strategy',
-  participants: ['alice', 'bob'],
+  // 'coordinator' (this client's own identity) sends propose()/commit() below with no
+  // sender override, so it must be a declared participant too.
+  participants: ['coordinator', 'alice', 'bob'],
   ttlMs: 60_000,
 });
 
@@ -108,7 +110,10 @@ Structured decision with proposals, evaluations, objections, and votes.
 import { DecisionSession } from 'macp-sdk-typescript';
 
 const session = new DecisionSession(client);
-await session.start({ intent: '...', participants: ['alice'], ttlMs: 60_000 });
+// 'coordinator' (this client's own identity) sends propose()/vote()/commit() below,
+// so it must be a declared participant — Decision mode's default governance policy
+// rejects a mode action from a non-participant sender with FORBIDDEN.
+await session.start({ intent: '...', participants: ['coordinator', 'alice'], ttlMs: 60_000 });
 await session.propose({ proposalId: 'p1', option: 'A', rationale: '...' });
 await session.evaluate({ proposalId: 'p1', recommendation: 'approve', confidence: 0.9 });
 await session.raiseObjection({ proposalId: 'p1', reason: 'risk', severity: 'high' });
@@ -118,7 +123,7 @@ await session.commit({ action: 'decided', authorityScope: 'team', reason: '...'
 // Projection queries
 session.projection.voteTotals();                 // { p1: 1 }
 session.projection.majorityWinner();             // 'p1'
-session.projection.hasBlockingObjection('p1');   // true (severity: high)
+session.projection.hasBlockingObjection('p1');   // false (only severity 'critical' blocks)
 ```
 
 ### Proposal Mode
@@ -126,13 +131,17 @@ session.projection.hasBlockingObjection('p1');   // true (severity: high)
 Proposal and counterproposal negotiation.
 
 ```typescript
-import { ProposalSession } from 'macp-sdk-typescript';
+import { Auth, ProposalSession } from 'macp-sdk-typescript';
 
 const session = new ProposalSession(client);
-await session.start({ intent: '...', participants: ['bob'], ttlMs: 60_000 });
+// 'coordinator' sends propose() below, so it must be a declared participant (same
+// FORBIDDEN rule as Decision mode). Proposal mode's default policy also requires
+// *every* participant to accept() before commit() — not just the non-proposing ones.
+await session.start({ intent: '...', participants: ['coordinator', 'bob'], ttlMs: 60_000 });
 await session.propose({ proposalId: 'p1', title: 'Plan A', summary: '...' });
 await session.counterPropose({ proposalId: 'p2', supersedesProposalId: 'p1', title: 'Plan B' });
 await session.accept({ proposalId: 'p2', reason: 'better' });
+await session.accept({ proposalId: 'p2', reason: 'bob agrees', sender: 'bob', auth: Auth.devAgent('bob') });
 await session.commit({ action: 'proposal.accepted', authorityScope: 'team', reason: '...' });
 
 // Projection queries
@@ -146,14 +155,18 @@ session.projection.isTerminallyRejected('p1');   // false
 Bounded task delegation.
 
 ```typescript
-import { TaskSession } from 'macp-sdk-typescript';
+import { Auth, TaskSession } from 'macp-sdk-typescript';
 
 const session = new TaskSession(client);
 await session.start({ intent: '...', participants: ['worker'], ttlMs: 120_000 });
 await session.requestTask({ taskId: 't1', title: 'Build feature', instructions: '...' });
-await session.acceptTask({ taskId: 't1', assignee: 'worker' });
-await session.updateTask({ taskId: 't1', status: 'working', progress: 0.5, message: 'halfway' });
-await session.completeTask({ taskId: 't1', assignee: 'worker', summary: 'done' });
+// The coordinator requests and commits, but every task-side action must be sent by the
+// assignee itself: Task mode's default policy rejects an acceptTask/updateTask/
+// completeTask from any other sender with FORBIDDEN.
+const asWorker = { sender: 'worker', auth: Auth.devAgent('worker') };
+await session.acceptTask({ taskId: 't1', assignee: 'worker', ...asWorker });
+await session.updateTask({ taskId: 't1', status: 'working', progress: 0.5, message: 'halfway', ...asWorker });
+await session.completeTask({ taskId: 't1', assignee: 'worker', summary: 'done', ...asWorker });
 await session.commit({ action: 'task.completed', authorityScope: 'lead', reason: '...' });
 
 // Projection queries
@@ -167,13 +180,22 @@ session.projection.activeTasks();      // []
 Responsibility transfer between participants.
 
 ```typescript
-import { HandoffSession } from 'macp-sdk-typescript';
+import { Auth, HandoffSession } from 'macp-sdk-typescript';
 
 const session = new HandoffSession(client);
-await session.start({ intent: '...', participants: ['bob'], ttlMs: 60_000 });
+// Handoff's SessionStart itself requires >= 2 participants, AND the initiator
+// ('coordinator', this client's own identity) must be one of them.
+await session.start({ intent: '...', participants: ['coordinator', 'bob'], ttlMs: 60_000 });
 await session.offer({ handoffId: 'h1', targetParticipant: 'bob', scope: 'frontend' });
 await session.addContext({ handoffId: 'h1', contentType: 'application/json', context: buf });
-await session.acceptHandoff({ handoffId: 'h1', acceptedBy: 'bob' });
+// Only the offer's targetParticipant may accept — sender must be 'bob', not the
+// session's own coordinator identity.
+await session.acceptHandoff({
+  handoffId: 'h1',
+  acceptedBy: 'bob',
+  sender: 'bob',
+  auth: Auth.devAgent('bob'),
+});
 await session.commit({ action: 'handoff.accepted', authorityScope: 'team', reason: '...' });
 
 // Projection queries
@@ -186,19 +208,24 @@ session.projection.pendingHandoffs();     // []
 Threshold-based approval voting.
 
 ```typescript
-import { QuorumSession } from 'macp-sdk-typescript';
+import { Auth, QuorumSession } from 'macp-sdk-typescript';
 
 const session = new QuorumSession(client);
 await session.start({ intent: '...', participants: ['alice', 'bob', 'carol'], ttlMs: 60_000 });
 await session.requestApproval({ requestId: 'r1', action: 'deploy', summary: '...', requiredApprovals: 2 });
-await session.approve({ requestId: 'r1', reason: 'ok' });
+// Ballots must come from a declared participant ('coordinator' is not one here), so each
+// approve() needs its own sender. commit() additionally requires the threshold to be met —
+// with requiredApprovals: 2, a single approval makes the runtime reject the Commitment
+// with INVALID_ENVELOPE.
+await session.approve({ requestId: 'r1', reason: 'ok', sender: 'alice', auth: Auth.devAgent('alice') });
+await session.approve({ requestId: 'r1', reason: 'ok', sender: 'bob', auth: Auth.devAgent('bob') });
 await session.commit({ action: 'quorum.approved', authorityScope: 'ops', reason: '...' });
 
 // Projection queries
-session.projection.hasQuorum('r1');              // true/false
-session.projection.approvalCount('r1');          // number
-session.projection.remainingVotesNeeded('r1');   // number
-session.projection.votedSenders('r1');           // string[]
+session.projection.hasQuorum('r1');              // true
+session.projection.approvalCount('r1');          // 2
+session.projection.remainingVotesNeeded('r1');   // 0
+session.projection.votedSenders('r1');           // ['alice', 'bob']
 ```
 
 ## Agent Framework
@@ -412,12 +439,15 @@ npm run format             # Prettier
 npm test                   # Run unit + conformance tests
 npm run test:watch         # Watch mode
 npm run test:coverage      # With coverage (CI enforces thresholds from vitest.config.ts)
-npm run test:integration   # Integration tests (requires Docker runtime; not run in CI)
+npm run test:integration   # Integration tests (requires Docker runtime)
 ```
 
 CI (GitHub Actions) runs type-check, lint, format check, the coverage-gated
 test suite, and the build on Node 22 and 24 for every push and pull
-request, and posts a coverage summary comment on PRs.
+request, and posts a coverage summary comment on PRs. A separate workflow
+(`.github/workflows/integration.yml`) runs `npm run test:integration` against a live
+runtime service container on every pull request too — an example that no longer runs
+cleanly fails that workflow, not just a local check.
 
 ### Integration Tests
 

package/dist/client.d.ts

@@ -29,10 +29,21 @@ interface MacpClientOptions {
  * unknown codes. Used to populate {@link MacpTransportError.code}.
  */
 export declare function grpcStatusName(code: unknown): string | undefined;
-export type InlineErrorCallback = (error: {
+/**
+ * An inline `MACPError` frame on a `StreamSession` stream. Since runtime 0.9.0
+ * `code` is the error-codes registry code (`INVALID_ENVELOPE`,
+ * `POLICY_DENIED`, ...) — before, it held the status message text — and
+ * `messageId`/`details` identify the rejected envelope and carry the same
+ * structured details a unary `Ack` does (decode with `parseErrorDetails`).
+ */
+export interface InlineStreamError {
     code?: string;
     message?: string;
-}) => void;
+    sessionId?: string;
+    messageId?: string;
+    details?: Buffer;
+}
+export type InlineErrorCallback = (error: InlineStreamError) => void;
 export declare class MacpStream {
     private readonly call;
     private readonly queue;
@@ -56,9 +67,11 @@ export declare class MacpStream {
      * delivery, redeliveries included; see `GrpcTransportAdapter.lastSequence`
      * for a cursor that tracks the ordinal correctly.
      * Ordinals are stable across log compaction and runtime restart. Resuming
-     * below a compacted base returns `FAILED_PRECONDITION` (inspectable via
-     * `MacpTransportError.code`) rather than silently skipping history (runtime
-     * ≥ 0.5.0; older runtimes compared inclusively against a raw log index).
+     * below a compacted base is refused rather than silently skipping history
+     * (runtime ≥ 0.5.0; older runtimes compared inclusively against a raw log
+     * index): since runtime 0.9.0 as an inline `INVALID_ENVELOPE` error frame
+     * (see `onInlineError`) with the stream left open; on 0.5.0–0.8.x it ended
+     * the stream with `FAILED_PRECONDITION` (`MacpTransportError.code`).
      */
     sendSubscribe(sessionId: string, afterSequence?: number): Promise<void>;
     responses(): AsyncGenerator<Envelope, void, void>;

package/dist/client.js

@@ -156,13 +156,17 @@ class MacpStream {
             }
             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 });
+                logging_1.logger.warn('inline stream error', {
+                    code: chunk.error.code,
+                    message: chunk.error.message,
+                    messageId: chunk.error.messageId,
+                });
                 for (const cb of this.inlineErrorCallbacks)
                     cb(chunk.error);
             }
         });
         call.on('error', (error) => {
-            this.queue.push(new errors_1.MacpTransportError(error.details || error.message, grpcStatusName(error.code)));
+            this.queue.push(new errors_1.MacpTransportError(error.details || error.message, grpcStatusName(error.code), (0, errors_1.macpErrorCodeFromMetadata)(grpcMetadataEntries(error.metadata))));
         });
         call.on('end', () => {
             this.queue.push(STREAM_END);
@@ -198,9 +202,11 @@ class MacpStream {
      * delivery, redeliveries included; see `GrpcTransportAdapter.lastSequence`
      * for a cursor that tracks the ordinal correctly.
      * Ordinals are stable across log compaction and runtime restart. Resuming
-     * below a compacted base returns `FAILED_PRECONDITION` (inspectable via
-     * `MacpTransportError.code`) rather than silently skipping history (runtime
-     * ≥ 0.5.0; older runtimes compared inclusively against a raw log index).
+     * below a compacted base is refused rather than silently skipping history
+     * (runtime ≥ 0.5.0; older runtimes compared inclusively against a raw log
+     * index): since runtime 0.9.0 as an inline `INVALID_ENVELOPE` error frame
+     * (see `onInlineError`) with the stream left open; on 0.5.0–0.8.x it ended
+     * the stream with `FAILED_PRECONDITION` (`MacpTransportError.code`).
      */
     sendSubscribe(sessionId, afterSequence = 0) {
         if (this.closed)
@@ -318,17 +324,23 @@ class MacpClient {
         const resolved = deadlineMs ?? this.defaultDeadlineMs;
         return resolved ? new Date(Date.now() + resolved) : undefined;
     }
-    unary(method, request, auth, deadlineMs, ackStatuses) {
+    unary(method, request, auth, deadlineMs, ackStatuses, registryCodeAsAck = false) {
         return new Promise((resolve, reject) => {
             const callback = (error, response) => {
                 if (error) {
                     const statusName = grpcStatusName(error.code);
-                    const mappedCode = statusName ? ackStatuses?.[statusName] : undefined;
+                    const entries = grpcMetadataEntries(error.metadata);
+                    // Runtime ≥ 0.9.0 names the registry code in `macp-error-code`
+                    // metadata; several codes share one gRPC status, so when the call
+                    // opts in, that code wins over the status-name map (which remains
+                    // the fallback for older runtimes that send no such key).
+                    const macpErrorCode = (0, errors_1.macpErrorCodeFromMetadata)(entries);
+                    const mappedCode = (registryCodeAsAck ? macpErrorCode : undefined) ?? (statusName ? ackStatuses?.[statusName] : undefined);
                     if (mappedCode) {
-                        reject(new errors_1.MacpAckError({ ok: false, error: { code: mappedCode, message: error.details || error.message } }, grpcMetadataEntries(error.metadata)));
+                        reject(new errors_1.MacpAckError({ ok: false, error: { code: mappedCode, message: error.details || error.message } }, entries));
                     }
                     else {
-                        reject(new errors_1.MacpTransportError(error.details || error.message, statusName));
+                        reject(new errors_1.MacpTransportError(error.details || error.message, statusName, macpErrorCode));
                     }
                 }
                 else {
@@ -375,7 +387,9 @@ class MacpClient {
         // 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 });
+        // That status map is the pre-0.9.0 fallback: a `macp-error-code` key
+        // (runtime ≥ 0.9.0) supplies the exact registry code instead.
+        { ALREADY_EXISTS: constants_1.SESSION_ALREADY_EXISTS, FAILED_PRECONDITION: constants_1.POLICY_DENIED }, true);
         const ack = response.ack;
         // Duplicate acks are success — the message was already accepted
         if (ack?.duplicate)

package/dist/commitment-hash.d.ts

@@ -69,3 +69,29 @@ export declare function commitmentHash(payload: CommitmentPayload): string;
  * `fullmatch` semantics for this pattern.
  */
 export declare function isCanonicalCommitmentHash(value: string): boolean;
+/**
+ * Result of {@link verifyCommitmentHash} (RFC-MACP-0013 §6.1). `cannot_verify`
+ * is a verdict on the payload encoding — never on the claim.
+ */
+export type VerifyOutcome = 'match' | 'mismatch' | 'cannot_verify';
+/**
+ * Verifies a claimed commitment hash against a `CommitmentPayload`'s Protobuf
+ * wire encoding (RFC-MACP-0013 §6.1), returning exactly one of:
+ *
+ * - `'match'` — the claim equals the canonical hash of the decoded payload;
+ * - `'mismatch'` — it does not, including any claim not in canonical form
+ *   (`SHA256:` prefix, uppercase hex, no prefix, surrounding whitespace):
+ *   the comparison is exact, never normalized;
+ * - `'cannot_verify'` — the encoding is outside what the
+ *   `macp-commitment-hash/1` label covers: an unknown field in the payload or
+ *   in `supersedes` (§5), or an unparseable encoding — truncated, a known
+ *   field with the wrong wire type, invalid UTF-8 in a string, a group, or
+ *   field number 0 (§6.1 rule 1).
+ *
+ * Takes the wire bytes, not a decoded object, so unknown fields stay
+ * observable. A known field repeated on the wire follows Protobuf merge
+ * semantics (last scalar wins, `supersedes` merges), and a zero-length
+ * encoding is the all-default payload, which is hashable. Never throws: a
+ * non-byte `wire` is `'cannot_verify'`, a non-string claim `'mismatch'`.
+ */
+export declare function verifyCommitmentHash(wire: Uint8Array, claimedHash: string): VerifyOutcome;

package/dist/commitment-hash.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.canonicalizeCommitmentPayload = canonicalizeCommitmentPayload;
 exports.commitmentHash = commitmentHash;
 exports.isCanonicalCommitmentHash = isCanonicalCommitmentHash;
+exports.verifyCommitmentHash = verifyCommitmentHash;
 /**
  * RFC-MACP-0013 canonical commitment hashing.
  *
@@ -230,3 +231,182 @@ function commitmentHash(payload) {
 function isCanonicalCommitmentHash(value) {
     return /^sha256:[0-9a-f]{64}$/.test(value);
 }
+/** Thrown internally by the wire reader; never escapes this module. */
+class CannotVerify extends Error {
+}
+// `ignoreBOM: true` keeps a leading U+FEFF in a string field (the default
+// strips it, which would hash different bytes than the sender's); `fatal`
+// makes invalid UTF-8 throw, which RFC-MACP-0013 §6.1 rule 1 requires to be
+// cannot-verify rather than U+FFFD-substituted.
+const STRICT_UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+/**
+ * Minimal strict Protobuf wire reader for the two message types the
+ * `macp-commitment-hash/1` label covers. Hand-written rather than protobufjs
+ * because protobufjs silently skips unknown fields, and RFC-MACP-0013 §5
+ * requires an unknown field to be cannot-verify, never dropped.
+ */
+class WireReader {
+    buf;
+    pos = 0;
+    constructor(buf) {
+        this.buf = buf;
+    }
+    get done() {
+        return this.pos >= this.buf.length;
+    }
+    /** Varint as a Number. Exact up to 2^53; larger values are only ever compared against small bounds. */
+    varint() {
+        let result = 0;
+        let scale = 1;
+        for (let i = 0; i < 10; i++) {
+            if (this.pos >= this.buf.length)
+                throw new CannotVerify('truncated varint');
+            const byte = this.buf[this.pos++];
+            result += (byte & 0x7f) * scale;
+            if ((byte & 0x80) === 0)
+                return result;
+            scale *= 128;
+        }
+        throw new CannotVerify('varint longer than 10 bytes');
+    }
+    /** Reads a varint and reports only whether it is non-zero (proto3 bool). */
+    nonZeroVarint() {
+        return this.varint() !== 0;
+    }
+    bytes() {
+        const len = this.varint();
+        if (len > this.buf.length - this.pos)
+            throw new CannotVerify('truncated length-delimited field');
+        const out = this.buf.subarray(this.pos, this.pos + len);
+        this.pos += len;
+        return out;
+    }
+    string() {
+        try {
+            return STRICT_UTF8.decode(this.bytes());
+        }
+        catch (err) {
+            if (err instanceof CannotVerify)
+                throw err;
+            throw new CannotVerify('invalid UTF-8');
+        }
+    }
+    /** Field number and wire type of the next tag; field 0, groups, and wire types 6/7 are unparseable. */
+    tag() {
+        const key = this.varint();
+        if (key > 0xffffffff)
+            throw new CannotVerify('tag out of range');
+        const field = Math.floor(key / 8);
+        const wireType = key % 8;
+        if (field === 0)
+            throw new CannotVerify('field number 0');
+        if (wireType === 3 || wireType === 4)
+            throw new CannotVerify('group');
+        if (wireType > 5)
+            throw new CannotVerify(`invalid wire type ${wireType}`);
+        return { field, wireType };
+    }
+}
+const WIRE_VARINT = 0;
+const WIRE_LEN = 2;
+// Field numbers of the frozen set (RFC-MACP-0013 §5), in proto order.
+const PAYLOAD_STRING_FIELDS = {
+    1: 'commitmentId',
+    2: 'action',
+    3: 'authorityScope',
+    4: 'reason',
+    5: 'modeVersion',
+    6: 'policyVersion',
+    7: 'configurationVersion',
+};
+const FIELD_OUTCOME_POSITIVE = 8;
+const FIELD_SUPERSEDES = 9;
+const REF_STRING_FIELDS = { 1: 'sessionId', 2: 'commitmentHash' };
+function expectWireType(actual, expected) {
+    if (actual !== expected)
+        throw new CannotVerify('known field with the wrong wire type');
+}
+/** Merges one `CommitmentRef` occurrence into `ref` (Protobuf message merge: present sub-fields overwrite). */
+function mergeCommitmentRef(wire, ref) {
+    const r = new WireReader(wire);
+    while (!r.done) {
+        const { field, wireType } = r.tag();
+        const name = REF_STRING_FIELDS[field];
+        // `supersedes` carries exactly two fields (§5): anything else is outside the label.
+        if (name === undefined)
+            throw new CannotVerify(`unknown CommitmentRef field ${field}`);
+        expectWireType(wireType, WIRE_LEN);
+        ref[name] = r.string();
+    }
+}
+/** Strictly decodes a `CommitmentPayload` wire encoding; throws `CannotVerify` on anything §5/§6.1 excludes. */
+function decodeCommitmentPayloadStrict(wire) {
+    // Proto3 defaults: a zero-length encoding is the all-default payload (§6.1 rule 3).
+    const payload = {
+        commitmentId: '',
+        action: '',
+        authorityScope: '',
+        reason: '',
+        modeVersion: '',
+        policyVersion: '',
+        configurationVersion: '',
+        outcomePositive: false,
+    };
+    const r = new WireReader(wire);
+    while (!r.done) {
+        const { field, wireType } = r.tag();
+        const name = PAYLOAD_STRING_FIELDS[field];
+        if (name !== undefined) {
+            expectWireType(wireType, WIRE_LEN);
+            payload[name] = r.string(); // last value wins (§6.1 rule 2)
+        }
+        else if (field === FIELD_OUTCOME_POSITIVE) {
+            expectWireType(wireType, WIRE_VARINT);
+            payload.outcomePositive = r.nonZeroVarint();
+        }
+        else if (field === FIELD_SUPERSEDES) {
+            expectWireType(wireType, WIRE_LEN);
+            // Present even when empty; repeated occurrences merge (§6.1 rule 2).
+            payload.supersedes ??= { sessionId: '', commitmentHash: '' };
+            mergeCommitmentRef(r.bytes(), payload.supersedes);
+        }
+        else {
+            throw new CannotVerify(`field ${field} is outside the macp-commitment-hash/1 frozen set`);
+        }
+    }
+    return payload;
+}
+/**
+ * Verifies a claimed commitment hash against a `CommitmentPayload`'s Protobuf
+ * wire encoding (RFC-MACP-0013 §6.1), returning exactly one of:
+ *
+ * - `'match'` — the claim equals the canonical hash of the decoded payload;
+ * - `'mismatch'` — it does not, including any claim not in canonical form
+ *   (`SHA256:` prefix, uppercase hex, no prefix, surrounding whitespace):
+ *   the comparison is exact, never normalized;
+ * - `'cannot_verify'` — the encoding is outside what the
+ *   `macp-commitment-hash/1` label covers: an unknown field in the payload or
+ *   in `supersedes` (§5), or an unparseable encoding — truncated, a known
+ *   field with the wrong wire type, invalid UTF-8 in a string, a group, or
+ *   field number 0 (§6.1 rule 1).
+ *
+ * Takes the wire bytes, not a decoded object, so unknown fields stay
+ * observable. A known field repeated on the wire follows Protobuf merge
+ * semantics (last scalar wins, `supersedes` merges), and a zero-length
+ * encoding is the all-default payload, which is hashable. Never throws: a
+ * non-byte `wire` is `'cannot_verify'`, a non-string claim `'mismatch'`.
+ */
+function verifyCommitmentHash(wire, claimedHash) {
+    if (!(wire instanceof Uint8Array))
+        return 'cannot_verify';
+    let payload;
+    try {
+        payload = decodeCommitmentPayloadStrict(wire);
+    }
+    catch (err) {
+        if (err instanceof CannotVerify)
+            return 'cannot_verify';
+        throw err; // a bug in the reader, not a property of the input — surface it
+    }
+    return typeof claimedHash === 'string' && claimedHash === commitmentHash(payload) ? 'match' : 'mismatch';
+}

package/dist/constants.d.ts

@@ -29,3 +29,32 @@ export declare const POLICY_DENIED = "POLICY_DENIED";
 export declare const INVALID_SESSION_ID = "INVALID_SESSION_ID";
 export declare const UNKNOWN_POLICY_VERSION = "UNKNOWN_POLICY_VERSION";
 export declare const INVALID_POLICY_DEFINITION = "INVALID_POLICY_DEFINITION";
+/** Register/UnregisterPolicy against a file-loaded (read-only) policy registry — FAILED_PRECONDITION. */
+export declare const REGISTRY_READ_ONLY = "REGISTRY_READ_ONLY";
+/** Malformed control-plane request (bad page_size/page_token, missing descriptor, …) — INVALID_ARGUMENT. */
+export declare const INVALID_REQUEST = "INVALID_REQUEST";
+/** Stream/watch subscriber fell behind — RESOURCE_EXHAUSTED; resubscribe with `afterSequence`. */
+export declare const STREAM_LAGGED = "STREAM_LAGGED";
+/** GetManifest for an agent this runtime does not host — NOT_FOUND. */
+export declare const AGENT_NOT_FOUND = "AGENT_NOT_FOUND";
+export declare const DENY_VETO = "veto";
+export declare const DENY_VETO_HOLD = "veto_hold";
+export declare const DENY_QUORUM_NOT_MET = "quorum_not_met";
+export declare const DENY_THRESHOLD_NOT_MET = "threshold_not_met";
+export declare const DENY_CONFIDENCE_BELOW_MINIMUM = "confidence_below_minimum";
+export declare const DENY_EVALUATION_REQUIRED = "evaluation_required";
+export declare const DENY_NO_VOTES = "no_votes";
+export declare const DENY_DECLINE_OVER_APPROVAL = "decline_over_approval";
+export declare const DENY_DECLINE_NOT_BACKED = "decline_not_backed";
+export declare const DENY_CRITERION_NOT_MET = "criterion_not_met";
+export declare const DENY_OUTPUT_REQUIRED = "output_required";
+export declare const DENY_REASSIGNMENT_NOT_ALLOWED = "reassignment_not_allowed";
+export declare const DENY_UNSUPPORTED_SCHEMA_VERSION = "unsupported_schema_version";
+export declare const DENY_INVALID_RULES = "invalid_rules";
+export declare const DENY_UNSPECIFIED = "unspecified";
+/**
+ * The denial codes the reference evaluator emits. A custom evaluator may send
+ * others — `PolicyDenial.code` passes them through unchanged, so treat a code
+ * not in this set as {@link DENY_UNSPECIFIED}.
+ */
+export declare const KNOWN_DENY_CODES: ReadonlySet<string>;

package/dist/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INVALID_POLICY_DEFINITION = exports.UNKNOWN_POLICY_VERSION = exports.INVALID_SESSION_ID = exports.POLICY_DENIED = exports.INTERNAL_ERROR = exports.RATE_LIMITED = exports.PAYLOAD_TOO_LARGE = exports.DUPLICATE_MESSAGE = exports.UNAUTHENTICATED = exports.FORBIDDEN = exports.MODE_NOT_SUPPORTED = exports.SESSION_NOT_OPEN = exports.SESSION_NOT_FOUND = exports.SESSION_ALREADY_EXISTS = exports.INVALID_ENVELOPE = exports.UNSUPPORTED_PROTOCOL_VERSION = exports.STANDARD_MODES = exports.MODE_MULTI_ROUND = exports.MODE_QUORUM = exports.MODE_HANDOFF = exports.MODE_TASK = exports.MODE_PROPOSAL = exports.MODE_DECISION = exports.DEFAULT_POLICY_VERSION = exports.DEFAULT_CONFIGURATION_VERSION = exports.DEFAULT_MODE_VERSION = exports.MACP_VERSION = void 0;
+exports.KNOWN_DENY_CODES = exports.DENY_UNSPECIFIED = exports.DENY_INVALID_RULES = exports.DENY_UNSUPPORTED_SCHEMA_VERSION = exports.DENY_REASSIGNMENT_NOT_ALLOWED = exports.DENY_OUTPUT_REQUIRED = exports.DENY_CRITERION_NOT_MET = exports.DENY_DECLINE_NOT_BACKED = exports.DENY_DECLINE_OVER_APPROVAL = exports.DENY_NO_VOTES = exports.DENY_EVALUATION_REQUIRED = exports.DENY_CONFIDENCE_BELOW_MINIMUM = exports.DENY_THRESHOLD_NOT_MET = exports.DENY_QUORUM_NOT_MET = exports.DENY_VETO_HOLD = exports.DENY_VETO = exports.AGENT_NOT_FOUND = exports.STREAM_LAGGED = exports.INVALID_REQUEST = exports.REGISTRY_READ_ONLY = exports.INVALID_POLICY_DEFINITION = exports.UNKNOWN_POLICY_VERSION = exports.INVALID_SESSION_ID = exports.POLICY_DENIED = exports.INTERNAL_ERROR = exports.RATE_LIMITED = exports.PAYLOAD_TOO_LARGE = exports.DUPLICATE_MESSAGE = exports.UNAUTHENTICATED = exports.FORBIDDEN = exports.MODE_NOT_SUPPORTED = exports.SESSION_NOT_OPEN = exports.SESSION_NOT_FOUND = exports.SESSION_ALREADY_EXISTS = exports.INVALID_ENVELOPE = exports.UNSUPPORTED_PROTOCOL_VERSION = exports.STANDARD_MODES = exports.MODE_MULTI_ROUND = exports.MODE_QUORUM = exports.MODE_HANDOFF = exports.MODE_TASK = exports.MODE_PROPOSAL = exports.MODE_DECISION = exports.DEFAULT_POLICY_VERSION = exports.DEFAULT_CONFIGURATION_VERSION = exports.DEFAULT_MODE_VERSION = exports.MACP_VERSION = void 0;
 exports.MACP_VERSION = '1.0';
 exports.DEFAULT_MODE_VERSION = '1.0.0';
 exports.DEFAULT_CONFIGURATION_VERSION = 'config.default';
@@ -34,3 +34,52 @@ exports.POLICY_DENIED = 'POLICY_DENIED';
 exports.INVALID_SESSION_ID = 'INVALID_SESSION_ID';
 exports.UNKNOWN_POLICY_VERSION = 'UNKNOWN_POLICY_VERSION';
 exports.INVALID_POLICY_DEFINITION = 'INVALID_POLICY_DEFINITION';
+// Control-plane codes added in runtime 0.9.0 (carried in `macp-error-code`
+// metadata; see `MacpTransportError.macpErrorCode` / `MacpAckError.macpErrorCode`).
+/** Register/UnregisterPolicy against a file-loaded (read-only) policy registry — FAILED_PRECONDITION. */
+exports.REGISTRY_READ_ONLY = 'REGISTRY_READ_ONLY';
+/** Malformed control-plane request (bad page_size/page_token, missing descriptor, …) — INVALID_ARGUMENT. */
+exports.INVALID_REQUEST = 'INVALID_REQUEST';
+/** Stream/watch subscriber fell behind — RESOURCE_EXHAUSTED; resubscribe with `afterSequence`. */
+exports.STREAM_LAGGED = 'STREAM_LAGGED';
+/** GetManifest for an agent this runtime does not host — NOT_FOUND. */
+exports.AGENT_NOT_FOUND = 'AGENT_NOT_FOUND';
+// Structured POLICY_DENIED denial codes (`PolicyDenial.code`, runtime ≥ 0.9.0;
+// RFC-MACP-0012 §6.2). Open set — names match python-sdk's exports.
+exports.DENY_VETO = 'veto';
+exports.DENY_VETO_HOLD = 'veto_hold';
+exports.DENY_QUORUM_NOT_MET = 'quorum_not_met';
+exports.DENY_THRESHOLD_NOT_MET = 'threshold_not_met';
+exports.DENY_CONFIDENCE_BELOW_MINIMUM = 'confidence_below_minimum';
+exports.DENY_EVALUATION_REQUIRED = 'evaluation_required';
+exports.DENY_NO_VOTES = 'no_votes';
+exports.DENY_DECLINE_OVER_APPROVAL = 'decline_over_approval';
+exports.DENY_DECLINE_NOT_BACKED = 'decline_not_backed';
+exports.DENY_CRITERION_NOT_MET = 'criterion_not_met';
+exports.DENY_OUTPUT_REQUIRED = 'output_required';
+exports.DENY_REASSIGNMENT_NOT_ALLOWED = 'reassignment_not_allowed';
+exports.DENY_UNSUPPORTED_SCHEMA_VERSION = 'unsupported_schema_version';
+exports.DENY_INVALID_RULES = 'invalid_rules';
+exports.DENY_UNSPECIFIED = 'unspecified';
+/**
+ * The denial codes the reference evaluator emits. A custom evaluator may send
+ * others — `PolicyDenial.code` passes them through unchanged, so treat a code
+ * not in this set as {@link DENY_UNSPECIFIED}.
+ */
+exports.KNOWN_DENY_CODES = new Set([
+    exports.DENY_VETO,
+    exports.DENY_VETO_HOLD,
+    exports.DENY_QUORUM_NOT_MET,
+    exports.DENY_THRESHOLD_NOT_MET,
+    exports.DENY_CONFIDENCE_BELOW_MINIMUM,
+    exports.DENY_EVALUATION_REQUIRED,
+    exports.DENY_NO_VOTES,
+    exports.DENY_DECLINE_OVER_APPROVAL,
+    exports.DENY_DECLINE_NOT_BACKED,
+    exports.DENY_CRITERION_NOT_MET,
+    exports.DENY_OUTPUT_REQUIRED,
+    exports.DENY_REASSIGNMENT_NOT_ALLOWED,
+    exports.DENY_UNSUPPORTED_SCHEMA_VERSION,
+    exports.DENY_INVALID_RULES,
+    exports.DENY_UNSPECIFIED,
+]);

package/dist/decision.js

@@ -95,7 +95,10 @@ class DecisionSession {
     }
     async raiseObjection(input) {
         (0, validation_1.validateRequiredField)('proposalId', input.proposalId);
-        const severity = input.severity ? (0, validation_1.validateSeverity)(input.severity) : input.severity;
+        // Always send an explicit lowercase severity: runtime ≥ 0.9.0 sessions
+        // (semantics_rev 4) reject an empty one instead of defaulting to
+        // "medium", so the SDK applies that default itself (python-sdk parity).
+        const severity = (0, validation_1.validateSeverity)(input.severity ?? 'medium');
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_DECISION,
             messageType: 'Objection',

package/dist/errors.d.ts

@@ -8,12 +8,62 @@ export declare class MacpTransportError extends MacpSdkError {
      * `UNAUTHENTICATED`) when the underlying transport failure carried one.
      * Lets consumers distinguish, for example, watch-stream consumer lag
      * (`RESOURCE_EXHAUSTED` → reconnect) from an auth failure (`UNAUTHENTICATED`
-     * → do not reconnect), or a passive-subscribe resume below a compacted base
-     * (`FAILED_PRECONDITION`). Absent for locally-raised transport errors.
+     * → do not reconnect). Absent for locally-raised transport errors. For a
+     * runtime-raised MACP error prefer {@link macpErrorCode}.
      */
     readonly code?: string;
-    constructor(message: string, code?: string);
+    /**
+     * MACP error-codes registry code (e.g. `SESSION_NOT_FOUND`, `POLICY_DENIED`)
+     * from the status's `macp-error-code` trailing metadata (runtime ≥ 0.9.0).
+     * Branch on this rather than {@link code}: since 0.9.0 the gRPC status
+     * follows the registry's gRPC column, and several registry codes share one
+     * status (e.g. `INVALID_ENVELOPE` and `INVALID_SESSION_ID` are both
+     * `INVALID_ARGUMENT`). Absent for older runtimes, for statuses the runtime
+     * raised without a registry code, and for locally-raised errors.
+     */
+    readonly macpErrorCode?: string;
+    constructor(message: string, code?: string, macpErrorCode?: string);
+}
+/**
+ * One structured `POLICY_DENIED` reason (RFC-MACP-0012 §6.2, runtime ≥ 0.9.0).
+ *
+ * `code` is an open set: the reference evaluator emits `veto`, `veto_hold`,
+ * `quorum_not_met`, `threshold_not_met`, `confidence_below_minimum`,
+ * `evaluation_required`, `no_votes`, `decline_over_approval`,
+ * `decline_not_backed`, `criterion_not_met`, `output_required`,
+ * `reassignment_not_allowed`, `unsupported_schema_version`, `invalid_rules`
+ * and `unspecified` (exported as the `DENY_*` constants and
+ * {@link KNOWN_DENY_CODES}), but a custom evaluator may mint its own. `code`
+ * is the wire value passed through unchanged — treat one not in
+ * `KNOWN_DENY_CODES` as `unspecified`. `participants` lists the participant
+ * ids the reason concerns (e.g. a veto's objectors); since 0.9.0 they are no
+ * longer embedded in `message`.
+ */
+export interface PolicyDenial {
+    code: string;
+    message: string;
+    participants: string[];
 }
+/** Parsed MACP error `details` JSON: legacy `reasons` strings plus structured `denials`. */
+export interface MacpErrorDetails {
+    reasons: string[];
+    denials: PolicyDenial[];
+}
+/**
+ * Parse the JSON `details` the runtime attaches to a `POLICY_DENIED` error —
+ * found on `Ack.error.details`, an inline stream `MACPError.details`, or the
+ * `macp-error-details-bin` trailing metadata. Never throws: missing,
+ * non-JSON, or malformed input yields empty arrays; a `denials` entry that is
+ * not an object is dropped, and one without a string `message` is kept with
+ * `message: ''`. Pre-0.9.0 runtimes send `reasons` only,
+ * so `denials` is `[]` for them.
+ */
+export declare function parseErrorDetails(details: Buffer | Uint8Array | string | null | undefined): MacpErrorDetails;
+/** Value of the `macp-error-code` trailing-metadata key, if present (runtime ≥ 0.9.0). */
+export declare function macpErrorCodeFromMetadata(grpcMetadata?: Array<{
+    key: string;
+    value: string | Buffer;
+}>): string | undefined;
 /**
  * Structured NACK record. Mirrors python-sdk's `AckFailure` dataclass so
  * cross-SDK code can share the same shape when logging or persisting a
@@ -25,6 +75,11 @@ export interface AckFailure {
     sessionId: string;
     messageId: string;
     reasons: string[];
+    /**
+     * Structured policy-denial reasons (runtime ≥ 0.9.0). Empty for non-policy
+     * NACKs and for older runtimes, which send `reasons` strings only.
+     */
+    denials: PolicyDenial[];
 }
 export declare class MacpAckError extends MacpSdkError {
     readonly ack: Ack;
@@ -35,13 +90,19 @@ export declare class MacpAckError extends MacpSdkError {
     }>;
     /** Structured NACK record — parity with python-sdk `MacpAckError.failure`. */
     readonly failure: AckFailure;
+    /**
+     * The registry code from the `macp-error-code` metadata (runtime ≥ 0.9.0)
+     * when this NACK was synthesized from a gRPC status. Usually equal to
+     * `failure.code`; differs on the registry-mutation RPCs, which keep
+     * `failure.code: 'FAILED_PRECONDITION'` for compatibility while this names
+     * the precise cause (e.g. `REGISTRY_READ_ONLY`).
+     */
+    readonly macpErrorCode?: string;
     constructor(ack: Ack, grpcMetadata?: Array<{
         key: string;
         value: string | Buffer;
     }>);
-    private static _extractReasons;
-    private static _parseAckReasons;
-    private static _parseGrpcMetadataReasons;
+    private static _extractDetails;
 }
 export declare class MacpSessionError extends MacpSdkError {
     constructor(message: string);

package/dist/errors.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MacpIdentityMismatchError = exports.MacpRetryError = exports.MacpTimeoutError = exports.MacpSessionError = exports.MacpAckError = exports.MacpTransportError = exports.MacpSdkError = void 0;
+exports.parseErrorDetails = parseErrorDetails;
+exports.macpErrorCodeFromMetadata = macpErrorCodeFromMetadata;
 class MacpSdkError extends Error {
     constructor(message) {
         super(message);
@@ -14,80 +16,121 @@ class MacpTransportError extends MacpSdkError {
      * `UNAUTHENTICATED`) when the underlying transport failure carried one.
      * Lets consumers distinguish, for example, watch-stream consumer lag
      * (`RESOURCE_EXHAUSTED` → reconnect) from an auth failure (`UNAUTHENTICATED`
-     * → do not reconnect), or a passive-subscribe resume below a compacted base
-     * (`FAILED_PRECONDITION`). Absent for locally-raised transport errors.
+     * → do not reconnect). Absent for locally-raised transport errors. For a
+     * runtime-raised MACP error prefer {@link macpErrorCode}.
      */
     code;
-    constructor(message, code) {
+    /**
+     * MACP error-codes registry code (e.g. `SESSION_NOT_FOUND`, `POLICY_DENIED`)
+     * from the status's `macp-error-code` trailing metadata (runtime ≥ 0.9.0).
+     * Branch on this rather than {@link code}: since 0.9.0 the gRPC status
+     * follows the registry's gRPC column, and several registry codes share one
+     * status (e.g. `INVALID_ENVELOPE` and `INVALID_SESSION_ID` are both
+     * `INVALID_ARGUMENT`). Absent for older runtimes, for statuses the runtime
+     * raised without a registry code, and for locally-raised errors.
+     */
+    macpErrorCode;
+    constructor(message, code, macpErrorCode) {
         super(message);
         this.name = 'MacpTransportError';
         this.code = code;
+        if (macpErrorCode !== undefined)
+            this.macpErrorCode = macpErrorCode;
     }
 }
 exports.MacpTransportError = MacpTransportError;
+/**
+ * Parse the JSON `details` the runtime attaches to a `POLICY_DENIED` error —
+ * found on `Ack.error.details`, an inline stream `MACPError.details`, or the
+ * `macp-error-details-bin` trailing metadata. Never throws: missing,
+ * non-JSON, or malformed input yields empty arrays; a `denials` entry that is
+ * not an object is dropped, and one without a string `message` is kept with
+ * `message: ''`. Pre-0.9.0 runtimes send `reasons` only,
+ * so `denials` is `[]` for them.
+ */
+function parseErrorDetails(details) {
+    const empty = { reasons: [], denials: [] };
+    if (details === null || details === undefined)
+        return empty;
+    let parsed;
+    try {
+        const raw = typeof details === 'string' ? details : Buffer.from(details).toString('utf-8');
+        if (raw.length === 0)
+            return empty;
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return empty;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return empty;
+    const obj = parsed;
+    const reasons = Array.isArray(obj.reasons) ? obj.reasons.filter((r) => typeof r === 'string') : [];
+    const denials = [];
+    if (Array.isArray(obj.denials)) {
+        for (const d of obj.denials) {
+            if (typeof d !== 'object' || d === null)
+                continue;
+            const { code, message, participants } = d;
+            denials.push({
+                code: typeof code === 'string' && code.length > 0 ? code : 'unspecified',
+                // A denial without a string message is kept with '' (python-sdk
+                // parity, issue #168) — its code and participants still matter.
+                message: typeof message === 'string' ? message : '',
+                participants: Array.isArray(participants) ? participants.filter((p) => typeof p === 'string') : [],
+            });
+        }
+    }
+    return { reasons, denials };
+}
+/** Value of the `macp-error-code` trailing-metadata key, if present (runtime ≥ 0.9.0). */
+function macpErrorCodeFromMetadata(grpcMetadata) {
+    const entry = grpcMetadata?.find((item) => item.key === 'macp-error-code');
+    if (!entry)
+        return undefined;
+    const value = typeof entry.value === 'string' ? entry.value : entry.value.toString('utf-8');
+    return value.length > 0 ? value : undefined;
+}
 class MacpAckError extends MacpSdkError {
     ack;
     /** Optional gRPC trailing metadata for extracting additional error details. */
     grpcMetadata;
     /** Structured NACK record — parity with python-sdk `MacpAckError.failure`. */
     failure;
+    /**
+     * The registry code from the `macp-error-code` metadata (runtime ≥ 0.9.0)
+     * when this NACK was synthesized from a gRPC status. Usually equal to
+     * `failure.code`; differs on the registry-mutation RPCs, which keep
+     * `failure.code: 'FAILED_PRECONDITION'` for compatibility while this names
+     * the precise cause (e.g. `REGISTRY_READ_ONLY`).
+     */
+    macpErrorCode;
     constructor(ack, grpcMetadata) {
         super(`${ack.error?.code ?? 'UNKNOWN'}: ${ack.error?.message ?? 'runtime returned nack'}`);
         this.name = 'MacpAckError';
         this.ack = ack;
         this.grpcMetadata = grpcMetadata;
-        const reasons = MacpAckError._extractReasons(ack, grpcMetadata);
+        const { reasons, denials } = MacpAckError._extractDetails(ack, grpcMetadata);
         this.failure = {
             code: ack.error?.code ?? 'UNKNOWN',
             message: ack.error?.message ?? 'runtime returned nack',
             sessionId: ack.sessionId ?? ack.error?.sessionId ?? '',
             messageId: ack.messageId ?? ack.error?.messageId ?? '',
             reasons,
+            denials,
         };
+        const macpErrorCode = macpErrorCodeFromMetadata(grpcMetadata);
+        if (macpErrorCode !== undefined)
+            this.macpErrorCode = macpErrorCode;
     }
-    static _extractReasons(ack, grpcMetadata) {
-        // First try: parse from ack.error.details (matches Python _parse_ack_reasons)
-        const fromDetails = MacpAckError._parseAckReasons(ack);
-        if (fromDetails.length > 0)
-            return fromDetails;
-        // Second try: parse from gRPC trailing metadata (matches Python _parse_grpc_metadata_reasons)
-        return MacpAckError._parseGrpcMetadataReasons(grpcMetadata);
-    }
-    static _parseAckReasons(ack) {
-        if (!ack.error?.details)
-            return [];
-        try {
-            const details = ack.error.details;
-            const raw = Buffer.isBuffer(details) ? details.toString('utf-8') : String(details);
-            const parsed = JSON.parse(raw);
-            const reasons = parsed.reasons;
-            return Array.isArray(reasons) ? reasons : [];
-        }
-        catch {
-            return [];
-        }
-    }
-    static _parseGrpcMetadataReasons(grpcMetadata) {
-        if (!grpcMetadata)
-            return [];
-        try {
-            for (const item of grpcMetadata) {
-                if (item.key === 'macp-error-details-bin') {
-                    const data = Buffer.isBuffer(item.value)
-                        ? item.value.toString('utf-8')
-                        : typeof item.value === 'string'
-                            ? item.value
-                            : Buffer.from(item.value).toString('utf-8');
-                    const parsed = JSON.parse(data);
-                    const reasons = parsed.reasons;
-                    return Array.isArray(reasons) ? reasons : [];
-                }
-            }
-        }
-        catch {
-            // Intentionally swallowed — matches Python's bare except
-        }
-        return [];
+    static _extractDetails(ack, grpcMetadata) {
+        // First try: ack.error.details (matches Python _parse_ack_reasons)
+        const fromAck = parseErrorDetails(ack.error?.details);
+        if (fromAck.reasons.length > 0 || fromAck.denials.length > 0)
+            return fromAck;
+        // Second try: gRPC trailing metadata (matches Python _parse_grpc_metadata_reasons)
+        const entry = grpcMetadata?.find((item) => item.key === 'macp-error-details-bin');
+        return parseErrorDetails(entry?.value);
     }
 }
 exports.MacpAckError = MacpAckError;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { Auth, type AuthConfig, type BearerAuthOptions } from './auth';
 export * from './base-session';
 export * from './client';
-export { commitmentHash, isCanonicalCommitmentHash } from './commitment-hash';
+export { commitmentHash, isCanonicalCommitmentHash, verifyCommitmentHash, type VerifyOutcome } from './commitment-hash';
 export * from './constants';
 export * from './decision';
 export * from './envelope';

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.logger = exports.configureLogging = exports.isCanonicalCommitmentHash = exports.commitmentHash = exports.Auth = void 0;
+exports.agent = exports.VERSION = exports.logger = exports.configureLogging = exports.verifyCommitmentHash = 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,7 +46,8 @@ 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 `commitmentHash` and `isCanonicalCommitmentHash`.
+// Commitment hash: export `commitmentHash`, `isCanonicalCommitmentHash`, and
+// the RFC-MACP-0013 §6.1 verifier `verifyCommitmentHash`.
 // `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
@@ -55,6 +56,7 @@ __exportStar(require("./client"), exports);
 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; } });
+Object.defineProperty(exports, "verifyCommitmentHash", { enumerable: true, get: function () { return commitment_hash_1.verifyCommitmentHash; } });
 __exportStar(require("./constants"), exports);
 __exportStar(require("./decision"), exports);
 __exportStar(require("./envelope"), exports);

package/dist/types.d.ts

@@ -173,6 +173,7 @@ export interface DecisionEvaluationPayload {
 export interface DecisionObjectionPayload {
     proposalId: string;
     reason: string;
+    /** `critical` | `high` | `medium` | `low` (case-insensitive; sent lowercase). Defaults to `medium`. */
     severity?: string;
 }
 export interface DecisionVotePayload {

package/dist/validation.d.ts

@@ -1,5 +1,5 @@
 /**
- * Validate that `sid` is a lowercase UUID v4/v7 or base64url (22+ chars).
+ * Validate that `sid` is a lowercase UUID v4/v7 or base64url (22–128 chars).
  *
  * Mirrors the runtime's **no-fall-through** rule (issue #108.1, and
  * `macp-sdk-python`'s `validate_session_id`, `validation.py:33-58`, which

package/dist/validation.js

@@ -20,9 +20,12 @@ const errors_1 = require("./errors");
 const UUID_SHAPE_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
 // Strict lowercase UUID v4/v7 (version nibble 4 or 7, RFC 9562 variant 8/9/a/b).
 const UUID_V4V7_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[47][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
-const BASE64URL_RE = /^[A-Za-z0-9_-]{22,}$/;
+// 22–128 chars: the 128 cap is RFC-MACP-0004 §11.2's portability floor, which
+// runtime ≥ 0.9.0 enforces at SessionStart (INVALID_SESSION_ID). The charset is
+// ASCII, so 128 chars == 128 bytes.
+const BASE64URL_RE = /^[A-Za-z0-9_-]{22,128}$/;
 /**
- * Validate that `sid` is a lowercase UUID v4/v7 or base64url (22+ chars).
+ * Validate that `sid` is a lowercase UUID v4/v7 or base64url (22–128 chars).
  *
  * Mirrors the runtime's **no-fall-through** rule (issue #108.1, and
  * `macp-sdk-python`'s `validate_session_id`, `validation.py:33-58`, which
@@ -44,7 +47,7 @@ function validateSessionId(sid) {
     }
     if (BASE64URL_RE.test(sid))
         return;
-    throw new errors_1.MacpSessionError(`session_id must be a lowercase UUID v4/v7 or base64url (22+ chars), got: ${sid}`);
+    throw new errors_1.MacpSessionError(`session_id must be a lowercase UUID v4/v7 or base64url (22–128 chars), got: ${sid}`);
 }
 const VALID_VOTES = new Set(['APPROVE', 'REJECT', 'ABSTAIN']);
 function validateVote(value) {

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * Kept in sync with package.json by release-please (see the
  * `x-release-please-version` annotation).
  */
-export declare const VERSION = "0.14.1";
+export declare const VERSION = "0.16.0";

package/dist/version.js

@@ -7,4 +7,4 @@ exports.VERSION = void 0;
  * Kept in sync with package.json by release-please (see the
  * `x-release-please-version` annotation).
  */
-exports.VERSION = '0.14.1'; // x-release-please-version
+exports.VERSION = '0.16.0'; // x-release-please-version

package/dist/watchers.d.ts

@@ -53,13 +53,33 @@ export declare class RootsWatcher {
  * A missing/invalid credential surfaces as `code === 'UNAUTHENTICATED'` — fix
  * auth, do not reconnect.
  */
+/**
+ * One `WatchSignals` frame: the Signal envelope plus whether the runtime
+ * authenticated its `sender` (RFC-MACP-0004 §4.1, runtime ≥ 0.9.0).
+ */
+export interface SignalEvent {
+    envelope: Envelope;
+    /**
+     * `true` only when the runtime authenticated the Signal's `sender` (JWT or
+     * static-token auth). `false` in dev mode and on runtimes that predate the
+     * field — the safe direction. A Signal with `false` MUST NOT influence
+     * operational decisions (RFC-MACP-0004 §4.1).
+     */
+    senderAuthenticated: boolean;
+}
 export declare class SignalWatcher {
     private readonly client;
     private readonly auth?;
     constructor(client: MacpClient, options?: {
         auth?: AuthConfig;
     });
+    /**
+     * Signal envelopes only. Does not say whether a Signal's `sender` was
+     * authenticated — use {@link events} wherever a Signal can drive a decision.
+     */
     signals(signal?: AbortSignal): AsyncGenerator<Envelope, void, void>;
+    /** Signal envelopes paired with the runtime's `sender_authenticated` verdict. */
+    events(signal?: AbortSignal): AsyncGenerator<SignalEvent, void, void>;
     watch(handler: (envelope: Envelope) => void | Promise<void>): Promise<void>;
     nextSignal(): Promise<Envelope>;
 }

package/dist/watchers.js

@@ -55,7 +55,9 @@ function serverStreamToAsyncGenerator(stream) {
         // WatchSignals with UNAUTHENTICATED (fix auth, do NOT reconnect).
         const code = (0, client_1.grpcStatusName)(error.code);
         const serviceErr = error;
-        const wrapped = new errors_1.MacpTransportError(serviceErr.details || error.message, code);
+        const wrapped = new errors_1.MacpTransportError(serviceErr.details || error.message, code, (0, errors_1.macpErrorCodeFromMetadata)(serviceErr.metadata
+            ? serviceErr.metadata.get('macp-error-code').map((value) => ({ key: 'macp-error-code', value }))
+            : undefined));
         queue.push({ error: wrapped });
         if (resolve) {
             resolve();
@@ -164,16 +166,6 @@ class RootsWatcher {
     }
 }
 exports.RootsWatcher = RootsWatcher;
-/**
- * Watches the ambient signal plane. **Requires auth** as of runtime 0.5.0: if
- * no credential is configured on the watcher or the client, iterating
- * {@link SignalWatcher.signals} throws immediately (via `client.watchSignals`).
- *
- * Consumer lag terminates the stream with a coded `MacpTransportError`
- * (`code === 'RESOURCE_EXHAUSTED'`); the correct response is to reconnect.
- * A missing/invalid credential surfaces as `code === 'UNAUTHENTICATED'` — fix
- * auth, do not reconnect.
- */
 class SignalWatcher {
     client;
     auth;
@@ -181,15 +173,25 @@ class SignalWatcher {
         this.client = client;
         this.auth = options?.auth;
     }
+    /**
+     * Signal envelopes only. Does not say whether a Signal's `sender` was
+     * authenticated — use {@link events} wherever a Signal can drive a decision.
+     */
     async *signals(signal) {
+        for await (const event of this.events(signal))
+            yield event.envelope;
+    }
+    /** Signal envelopes paired with the runtime's `sender_authenticated` verdict. */
+    async *events(signal) {
         const stream = this.client.watchSignals(this.auth);
         if (signal) {
             signal.addEventListener('abort', () => stream.cancel(), { once: true });
         }
         const gen = serverStreamToAsyncGenerator(stream);
         for await (const response of gen) {
+            // Strict `=== true`: anything but an explicit true is unauthenticated.
             if (response.envelope)
-                yield response.envelope;
+                yield { envelope: response.envelope, senderAuthenticated: response.senderAuthenticated === true };
         }
     }
     async watch(handler) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macp-sdk-typescript",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "description": "TypeScript SDK for the MACP Rust runtime",
   "license": "Apache-2.0",
   "type": "commonjs",
@@ -56,7 +56,7 @@
   "dependencies": {
     "@grpc/grpc-js": "^1.14.3",
     "@grpc/proto-loader": "^0.8.0",
-    "@multiagentcoordinationprotocol/proto": "^0.1.10",
+    "@multiagentcoordinationprotocol/proto": "^0.1.11",
     "protobufjs": "^8.6.5"
   },
   "devDependencies": {