macp-sdk-typescript 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -4,6 +4,83 @@ 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.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
+
+* **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))
+
+## [0.14.1](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.14.0...v0.14.1) (2026-10-03)
+
+### Added
+
+- **`TaskProjection.rejections: TaskRejectRecord[]`** (issue #151; a
+  cross-SDK parity audit against `macp-sdk-python`'s `TaskRejectRecord`,
+  `src/macp_sdk/task.py:53-58`). `TaskReject` now appends an unconditional
+  audit record — `taskId`, `assignee`, `reason?`, `sender` (from the
+  envelope, not the payload) — matching the convention already established
+  for `updates`/`completions`/`failures`. A `TaskReject` for an unknown
+  `taskId` still records a `rejections` entry (no crash, no silent drop) but
+  creates no `tasks` entry, unchanged from today. Deliberately does not fall
+  back `assignee` to the envelope sender the way Python's `p.assignee or
+  envelope.sender` does — this SDK's own sibling `TaskComplete`/`TaskFail`
+  handlers spread the payload's `assignee` as-is with no such fallback, and
+  intra-SDK consistency with that established pattern takes precedence here.
+
+### Fixed
+
+- **`BaseProjection` phase no longer regresses once `Committed`, and
+  `DecisionProjection` no longer lets a replayed `Proposal` rewind phase
+  from `Voting` back to `Evaluation` after voting has begun** (issue #150,
+  issue #153; found by a cross-SDK parity audit against `macp-sdk-python`'s
+  `_set_phase()`, `src/macp_sdk/base_projection.py:289-313`). All five
+  built-in mode projections now route every phase write through a new
+  shared, protected `setPhase()` choke point on `BaseProjection` that
+  no-ops once `phase === 'Committed'`, instead of assigning `this.phase`
+  directly at each of the (previously) 12 call sites across
+  `decision.ts`/`proposal.ts`/`task.ts`/`quorum.ts`/`handoff.ts` — only
+  `decision.ts`'s own Vote-branch guard protected this before. RFC-MACP-0007
+  §5 rule 6 separately requires a runtime to reject any
+  `Proposal`/`Evaluation`/`Objection` after the first accepted `Vote`;
+  `DecisionProjection`'s `Proposal` handler now guards on the pre-
+  `Evaluation` phase value (`if (this.phase === 'Proposal')
+  this.setPhase('Evaluation')`) so a replayed/retried `Proposal` (same
+  `proposalId`, a distinct `messageId` that still passes
+  `applyEnvelope`'s `message_id` dedup gate) can no longer rewind `phase`
+  back to `'Evaluation'` once voting has begun. `BaseProjection.
+  applyEnvelope`'s own direct `this.phase = 'Committed'` assignment for a
+  `Commitment` envelope is deliberately left untouched — exact parity with
+  Python's own `_set_phase()` docstring, which documents the same bypass.
+- **`buildDecisionPolicy` now rejects a `+Infinity` voting weight** (issue
+  #152; found by a cross-SDK parity audit against `macp-sdk-python`'s
+  `math.isfinite` guard, `src/macp_sdk/policy.py:186`). The per-weight
+  validation guard changed from `weight <= 0 || Number.isNaN(weight)` to
+  `weight <= 0 || !Number.isFinite(weight)` — `!Number.isFinite` is `true`
+  for `NaN`, `+Infinity`, and `-Infinity` alike, closing the `+Infinity` gap
+  the old `Number.isNaN`-only check missed (a `+Infinity` weight serializes
+  to JSON `null`, which is schema-invalid against
+  `decision-rules.schema.json`). `-Infinity`/`NaN` continue to throw,
+  unchanged.
+- **`watchers.ts`'s 5 "stream ended before receiving a ..." sites now throw
+  `MacpTransportError` instead of a bare `Error`** (issue #154; parity with
+  `macp-sdk-python` PR #138). `ModeRegistryWatcher.nextChange()`,
+  `RootsWatcher.nextChange()`, `SignalWatcher.nextSignal()`,
+  `PolicyWatcher.nextChange()`, and `SessionLifecycleWatcher.nextChange()`
+  each threw a bare `Error` when their stream ended before yielding a value;
+  a caller's single `catch (e) { if (e instanceof MacpSdkError) ... }` now
+  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>;