macp-sdk-typescript 0.16.1 → 0.17.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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.17.0](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.16.1...v0.17.0) (2026-10-18)
+
+
+### ⚠ BREAKING CHANGES
+
+* **policy:** an untyped (JS/JSON) caller passing an off-domain rule value used to get a descriptor that a pre-0.9 runtime registered. That call now throws MacpSessionError at build time.
+* **task:** a TaskReject sent before any TaskAccept no longer sets TaskRecord.status to 'rejected'; the task stays 'requested' and remains in activeTasks(). TaskRejectRecord gains a required whileAssigned field.
+
+### Features
+
+* **handoff:** expose declined targets and the rule 3a re-offer bar ([#181](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/181)) ([dc61e08](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/dc61e08a552a729c6df9aa0dc19c31abfacd3189))
+* **policy:** refuse every off-domain rule value the 0.9 runtime enforces ([#183](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/183)) ([9afd316](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/9afd3167117dd99baadabb18f3199bc0140ae0ad))
+* **policy:** x- extension and _/$ annotation rules keys; policyRuleExtensions() ([#184](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/184)) ([84b3a14](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/84b3a14c2a414ebb7ff1042f5999ca17d961eab4))
+* **quorum:** effectiveQuorumThreshold and a policy-override bar for the readiness helpers ([#182](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/182)) ([63a00c4](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/63a00c459f676b93cba66c1a53924074c297c30f))
+
+
+### Bug Fixes
+
+* **task:** model a pre-assignment TaskReject as a personal decline (rule 2a) ([#179](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/issues/179)) ([2d56c32](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/commit/2d56c3290c9a77557fdbaa11ab8003498178b514))
+
 ## [0.16.1](https://github.com/multiagentcoordinationprotocol/macp-sdk-typescript/compare/v0.16.0...v0.16.1) (2026-10-18)
 
 

package/README.md

@@ -467,6 +467,19 @@ npm run test:integration
 docker rm -f macp-runtime-test
 ```
 
+## Runtime Compatibility
+
+This SDK requires **macp-runtime ≥ 0.9.0**. CI gates every PR on the
+integration suite against `macp-runtime:0.9.0`, the same pin as
+`macp-sdk-python`, and runs a non-blocking canary against `:latest`. Against
+an older runtime, the 0.9.0 behaviors the SDK models will not match. Examples:
+
+- the quorum policy-threshold override (`effectiveQuorumThreshold`);
+- task rule 2a personal declines;
+- the handoff rule 3a re-offer bar;
+- policy rule-domain admission and `ruleExtensions`;
+- `macp-error-code` statuses.
+
 ## Runtime Boundary
 
 This SDK is a **client** for the MACP Rust runtime. The runtime handles session state, message ordering, deduplication, TTL enforcement, and mode-specific validation. The SDK provides typed helpers for building and sending envelopes, and local projections for tracking state client-side.

package/dist/policy.d.ts

@@ -1,4 +1,4 @@
-import type { PolicyDescriptor } from './types';
+import type { InitializeResult, PolicyDescriptor } from './types';
 export interface CommitmentRules {
     authority?: 'initiator_only' | 'any_participant' | 'designated_role';
     /**
@@ -128,7 +128,40 @@ export interface HandoffPolicyRulesInput {
     acceptance?: HandoffAcceptanceRules;
     commitment?: CommitmentRules;
 }
-export interface DecisionPolicyOptions {
+/** `/properties/commitment/properties/authority` (all five modes). */
+export declare const COMMITMENT_AUTHORITIES: ReadonlySet<NonNullable<CommitmentRules['authority']>>;
+/** quorum-rules `/properties/abstention/properties/interpretation`. */
+export declare const ABSTENTION_INTERPRETATIONS: ReadonlySet<NonNullable<AbstentionRules['interpretation']>>;
+/** proposal-rules `/properties/acceptance/properties/criterion`. */
+export declare const PROPOSAL_ACCEPTANCE_CRITERIA: ReadonlySet<NonNullable<ProposalAcceptanceRules['criterion']>>;
+/** decision-rules `/properties/objection_handling/properties/critical_objection_action`. */
+export declare const CRITICAL_OBJECTION_ACTIONS: ReadonlySet<NonNullable<ObjectionHandlingRules['criticalObjectionAction']>>;
+/**
+ * Extra top-level `rules` keys every builder accepts (RFC-MACP-0012 §4),
+ * emitted after the standard sections in insertion order. Omitted or empty,
+ * the `rules` bytes are exactly what they were before these existed.
+ */
+export interface PolicyRuleExtras {
+    /**
+     * `x-` vendor-extension sections, e.g. `{ 'x-com.acme.audit': { level: 2 } }`.
+     * Keys must match `^x-[a-z0-9]+(\.[a-z0-9-]+)+$` and values must be objects.
+     * The runtime admits a key only if an embedder registered it (see
+     * `policyRuleExtensions()`; the stock server registers none), so the builder
+     * checks the key's shape, not whether this runtime will admit it.
+     */
+    extensions?: Record<string, Record<string, unknown>>;
+    /** `_`- or `$`-prefixed annotation keys, any JSON value; the runtime ignores them. */
+    annotations?: Record<string, unknown>;
+}
+/**
+ * The `x-` rule-extension keys a runtime advertises
+ * (`capabilities.policyRegistry.ruleExtensions`), or `[]` when it advertises
+ * none, including runtimes older than 0.9.0. Advisory: a descriptor carrying
+ * an unlisted key is refused at RegisterPolicy, but admission is what
+ * decides. Accepts the `initialize()` result or its `capabilities`.
+ */
+export declare function policyRuleExtensions(source: InitializeResult | InitializeResult['capabilities'] | null | undefined): string[];
+export interface DecisionPolicyOptions extends PolicyRuleExtras {
     /**
      * RFC-MACP-0012 rule schema version the runtime evaluates this policy
      * under (validated, never re-validated, at admission -- RFC-MACP-0012 §8
@@ -157,7 +190,37 @@ export interface DecisionPolicyOptions {
     schemaVersion?: 1 | 2 | 3;
 }
 export declare function buildDecisionPolicy(policyId: string, description: string, rules: DecisionPolicyRulesInput, options?: DecisionPolicyOptions): PolicyDescriptor;
-export declare function buildQuorumPolicy(policyId: string, description: string, rules: QuorumPolicyRulesInput): PolicyDescriptor;
-export declare function buildProposalPolicy(policyId: string, description: string, rules: ProposalPolicyRulesInput): PolicyDescriptor;
-export declare function buildTaskPolicy(policyId: string, description: string, rules: TaskPolicyRulesInput): PolicyDescriptor;
-export declare function buildHandoffPolicy(policyId: string, description: string, rules: HandoffPolicyRulesInput): PolicyDescriptor;
+export declare function buildQuorumPolicy(policyId: string, description: string, rules: QuorumPolicyRulesInput, options?: PolicyRuleExtras): PolicyDescriptor;
+/**
+ * The approval bar a Quorum session actually needs, or `null` when it is
+ * unsatisfiable.
+ *
+ * Since runtime 0.9.0 (S4, RFC-MACP-0011 §5 rule 6) a bound policy's
+ * `threshold` replaces the `ApprovalRequest.requiredApprovals` payload value
+ * *as given*, even above the participant count, in which case the threshold
+ * is unreachable and a negative Commitment is eligible at once. Pass the
+ * result as `{ effectiveThreshold }` to the `QuorumProjection` readiness
+ * helpers (`null` included — they treat it as unreachable).
+ *
+ * A port of the runtime's `QuorumThreshold::effective` and
+ * `QuorumMode::effective_threshold`, with the same results as
+ * macp-sdk-python's `effective_quorum_threshold`:
+ *
+ * - no policy, no `threshold`, `value <= 0`/NaN, a non-numeric or boolean
+ *   `value`, a non-string `type`, or unparsable rules (the runtime's
+ *   `unwrap_or_default` path): `requiredApprovals`, unchanged;
+ * - `n_of_m` (the default `type`, and the runtime's `count` alias):
+ *   `max(1, ceil(value))`;
+ * - integer `percentage`: `max(1, ceil(value * n / 100))` in exact integer
+ *   arithmetic (RFC-MACP-0012 §4.2 forbids float division); fractional
+ *   `percentage`: `max(1, ceil(value * n / 100))`;
+ * - `percentage` with no participants, or an unknown `type`: `null`;
+ * - every result saturates at `2^32 - 1` (an infinite value included).
+ *
+ * `rules` may be a `PolicyDescriptor`, its JSON `rules` string/bytes, or the
+ * decoded object.
+ */
+export declare function effectiveQuorumThreshold(rules: PolicyDescriptor | string | Uint8Array | Record<string, unknown> | null | undefined, participantCount: number, requiredApprovals: number): number | null;
+export declare function buildProposalPolicy(policyId: string, description: string, rules: ProposalPolicyRulesInput, options?: PolicyRuleExtras): PolicyDescriptor;
+export declare function buildTaskPolicy(policyId: string, description: string, rules: TaskPolicyRulesInput, options?: PolicyRuleExtras): PolicyDescriptor;
+export declare function buildHandoffPolicy(policyId: string, description: string, rules: HandoffPolicyRulesInput, options?: PolicyRuleExtras): PolicyDescriptor;

package/dist/policy.js

@@ -1,13 +1,111 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CRITICAL_OBJECTION_ACTIONS = exports.PROPOSAL_ACCEPTANCE_CRITERIA = exports.ABSTENTION_INTERPRETATIONS = exports.COMMITMENT_AUTHORITIES = void 0;
+exports.policyRuleExtensions = policyRuleExtensions;
 exports.buildDecisionPolicy = buildDecisionPolicy;
 exports.buildQuorumPolicy = buildQuorumPolicy;
+exports.effectiveQuorumThreshold = effectiveQuorumThreshold;
 exports.buildProposalPolicy = buildProposalPolicy;
 exports.buildTaskPolicy = buildTaskPolicy;
 exports.buildHandoffPolicy = buildHandoffPolicy;
 const errors_1 = require("./errors");
+// ── Rule value domains ──────────────────────────────────────────────
+// Runtime 0.9.0 validates every rule object against the canonical
+// spec `schemas/json/policy/*-rules.schema.json` and refuses an off-domain
+// value at RegisterPolicy with INVALID_POLICY_DEFINITION; the builders refuse
+// it client-side first. Same sets as macp-sdk-python's `macp_sdk.policy`;
+// tests/unit/policy-schema-parity.test.ts pins them against the schemas.
+// Typed against the rule-input unions so a widened union without a matching
+// set entry is a tsc error.
+/** `/properties/commitment/properties/authority` (all five modes). */
+exports.COMMITMENT_AUTHORITIES = new Set([
+    'initiator_only',
+    'any_participant',
+    'designated_role',
+]);
+/** quorum-rules `/properties/abstention/properties/interpretation`. */
+exports.ABSTENTION_INTERPRETATIONS = new Set([
+    'neutral',
+    'implicit_reject',
+    'ignored',
+]);
+/** proposal-rules `/properties/acceptance/properties/criterion`. */
+exports.PROPOSAL_ACCEPTANCE_CRITERIA = new Set([
+    'all_parties',
+    'counterparty',
+    'initiator',
+]);
+/** decision-rules `/properties/objection_handling/properties/critical_objection_action`. */
+exports.CRITICAL_OBJECTION_ACTIONS = new Set(['deny', 'finalize_decline', 'hold']);
+// decision-rules `/properties/voting/properties/quorum/properties/type`.
+const VOTING_QUORUM_TYPES = new Set(['count', 'percentage']);
+// RFC-MACP-0012 §4 key classes legal at the rules top level besides the
+// standard sections: `x-` vendor extensions (object-valued) and `_`/`$`
+// annotations (any value). Same patterns as the schemas' patternProperties.
+const EXTENSION_KEY_RE = /^x-[a-z0-9]+(\.[a-z0-9-]+)+$/;
+const ANNOTATION_KEY_RE = /^[_$]/;
+// An own enumerable key even for `__proto__` (a legal annotation name),
+// which plain assignment would turn into a prototype swap that
+// JSON.stringify then drops.
+function defineKey(rules, key, value) {
+    Object.defineProperty(rules, key, { value, enumerable: true, writable: true, configurable: true });
+}
+function addExtraKeys(rules, extras) {
+    for (const [key, value] of Object.entries(extras?.extensions ?? {})) {
+        if (Object.hasOwn(rules, key)) {
+            throw new errors_1.MacpSessionError(`extension key '${key}' collides with a standard rule section`);
+        }
+        if (!EXTENSION_KEY_RE.test(key)) {
+            throw new errors_1.MacpSessionError(`extension key '${key}' must match ${EXTENSION_KEY_RE.source} (e.g. 'x-com.acme.audit')`);
+        }
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            throw new errors_1.MacpSessionError(`extension '${key}' must be an object, got ${JSON.stringify(value)}`);
+        }
+        defineKey(rules, key, { ...value });
+    }
+    for (const [name, note] of Object.entries(extras?.annotations ?? {})) {
+        if (Object.hasOwn(rules, name)) {
+            throw new errors_1.MacpSessionError(`annotation key '${name}' collides with a standard rule section`);
+        }
+        if (!ANNOTATION_KEY_RE.test(name)) {
+            throw new errors_1.MacpSessionError(`annotation key '${name}' must start with '_' or '$'`);
+        }
+        defineKey(rules, name, note);
+    }
+}
+/**
+ * The `x-` rule-extension keys a runtime advertises
+ * (`capabilities.policyRegistry.ruleExtensions`), or `[]` when it advertises
+ * none, including runtimes older than 0.9.0. Advisory: a descriptor carrying
+ * an unlisted key is refused at RegisterPolicy, but admission is what
+ * decides. Accepts the `initialize()` result or its `capabilities`.
+ */
+function policyRuleExtensions(source) {
+    const capabilities = source && 'selectedProtocolVersion' in source
+        ? source.capabilities
+        : (source ?? undefined);
+    const registry = capabilities?.policyRegistry;
+    const keys = registry?.ruleExtensions;
+    return Array.isArray(keys) ? keys.filter((k) => typeof k === 'string') : [];
+}
+function checkEnum(fieldName, value, allowed) {
+    if (typeof value !== 'string' || !allowed.has(value)) {
+        throw new errors_1.MacpSessionError(`${fieldName} must be one of ${[...allowed].sort().join(', ')}, got ${JSON.stringify(value)}`);
+    }
+}
+// Number.isInteger rejects booleans, NaN and ±Infinity, so unlike Python's
+// `_check_min_int` no separate bool guard is needed.
+function checkMinInt(fieldName, value, minimum) {
+    if (!Number.isInteger(value) || value < minimum) {
+        throw new errors_1.MacpSessionError(`${fieldName} must be an integer >= ${minimum}, got ${JSON.stringify(value)}`);
+    }
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
 // ── Builder helpers ─────────────────────────────────────────────────
 function serializeCommitment(commitment) {
+    checkEnum('commitment.authority', commitment?.authority ?? 'initiator_only', exports.COMMITMENT_AUTHORITIES);
     // `authority: 'designated_role'` with an empty (or unset) `designatedRoles`
     // names no one, so no sender could ever satisfy it. All five rule schemas
     // reject this combination at admission (spec PR #121) via a root-level
@@ -117,6 +215,21 @@ function buildDecisionPolicy(policyId, description, rules, options) {
             }
         }
     }
+    // Value domains the runtime enforces since 0.9.0 (decision-rules.schema.json).
+    // Same order as macp-sdk-python's build_decision_policy.
+    const quorum = rules.voting?.quorum;
+    if (quorum !== undefined) {
+        checkEnum('voting.quorum_type', quorum.type, VOTING_QUORUM_TYPES);
+        if (!isFiniteNumber(quorum.value) || quorum.value < 0) {
+            throw new errors_1.MacpSessionError(`voting.quorum_value must be a finite number >= 0, got ${JSON.stringify(quorum.value)}`);
+        }
+    }
+    checkMinInt('objection_handling.veto_threshold', rules.objectionHandling?.vetoThreshold ?? 1, 1);
+    checkEnum('objection_handling.critical_objection_action', rules.objectionHandling?.criticalObjectionAction ?? 'deny', exports.CRITICAL_OBJECTION_ACTIONS);
+    const minimumConfidence = rules.evaluation?.minimumConfidence ?? 0;
+    if (!isFiniteNumber(minimumConfidence) || minimumConfidence < 0 || minimumConfidence > 1) {
+        throw new errors_1.MacpSessionError(`evaluation.minimum_confidence must be in [0.0, 1.0], got ${JSON.stringify(minimumConfidence)}`);
+    }
     // Decision-only: extend the shared commitment rules with the two keys
     // decision-rules.schema.json's commitment object allows and the other four
     // modes' commitment schemas do not -- `require_vote_quorum` and the
@@ -144,6 +257,7 @@ function buildDecisionPolicy(policyId, description, rules, options) {
         },
         commitment: commitmentSection,
     };
+    addExtraKeys(rulesJson, options);
     return {
         policyId,
         mode: 'macp.mode.decision.v1',
@@ -152,7 +266,7 @@ function buildDecisionPolicy(policyId, description, rules, options) {
         schemaVersion,
     };
 }
-function buildQuorumPolicy(policyId, description, rules) {
+function buildQuorumPolicy(policyId, description, rules, options) {
     const threshold = rules.threshold;
     if (threshold) {
         // Match the canonical quorum-rules schema's constraints before the runtime
@@ -186,6 +300,7 @@ function buildQuorumPolicy(policyId, description, rules) {
                 'defined semantics and must not be used.');
         }
     }
+    checkEnum('abstention.interpretation', rules.abstention?.interpretation ?? 'neutral', exports.ABSTENTION_INTERPRETATIONS);
     const rulesJson = {
         threshold: {
             type: rules.threshold?.type ?? 'n_of_m',
@@ -197,6 +312,7 @@ function buildQuorumPolicy(policyId, description, rules) {
         },
         commitment: serializeCommitment(rules.commitment),
     };
+    addExtraKeys(rulesJson, options);
     return {
         policyId,
         mode: 'macp.mode.quorum.v1',
@@ -205,7 +321,92 @@ function buildQuorumPolicy(policyId, description, rules) {
         schemaVersion: 1,
     };
 }
-function buildProposalPolicy(policyId, description, rules) {
+const U32_MAX = 2 ** 32 - 1;
+/**
+ * The approval bar a Quorum session actually needs, or `null` when it is
+ * unsatisfiable.
+ *
+ * Since runtime 0.9.0 (S4, RFC-MACP-0011 §5 rule 6) a bound policy's
+ * `threshold` replaces the `ApprovalRequest.requiredApprovals` payload value
+ * *as given*, even above the participant count, in which case the threshold
+ * is unreachable and a negative Commitment is eligible at once. Pass the
+ * result as `{ effectiveThreshold }` to the `QuorumProjection` readiness
+ * helpers (`null` included — they treat it as unreachable).
+ *
+ * A port of the runtime's `QuorumThreshold::effective` and
+ * `QuorumMode::effective_threshold`, with the same results as
+ * macp-sdk-python's `effective_quorum_threshold`:
+ *
+ * - no policy, no `threshold`, `value <= 0`/NaN, a non-numeric or boolean
+ *   `value`, a non-string `type`, or unparsable rules (the runtime's
+ *   `unwrap_or_default` path): `requiredApprovals`, unchanged;
+ * - `n_of_m` (the default `type`, and the runtime's `count` alias):
+ *   `max(1, ceil(value))`;
+ * - integer `percentage`: `max(1, ceil(value * n / 100))` in exact integer
+ *   arithmetic (RFC-MACP-0012 §4.2 forbids float division); fractional
+ *   `percentage`: `max(1, ceil(value * n / 100))`;
+ * - `percentage` with no participants, or an unknown `type`: `null`;
+ * - every result saturates at `2^32 - 1` (an infinite value included).
+ *
+ * `rules` may be a `PolicyDescriptor`, its JSON `rules` string/bytes, or the
+ * decoded object.
+ */
+function effectiveQuorumThreshold(rules, participantCount, requiredApprovals) {
+    let parsed = rules;
+    if (isPolicyDescriptor(parsed))
+        parsed = parsed.rules;
+    if (typeof parsed === 'string' || parsed instanceof Uint8Array) {
+        const text = typeof parsed === 'string' ? parsed : Buffer.from(parsed).toString('utf8');
+        if (!text)
+            return requiredApprovals;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return requiredApprovals;
+        }
+    }
+    if (!isPlainRecord(parsed))
+        return requiredApprovals;
+    const threshold = parsed.threshold;
+    if (!isPlainRecord(threshold))
+        return requiredApprovals;
+    const type = threshold.type === undefined ? 'n_of_m' : threshold.type;
+    const value = threshold.value === undefined ? 0 : threshold.value;
+    if (typeof type !== 'string' || typeof value !== 'number')
+        return requiredApprovals;
+    // NaN, 0 and negatives are all inert (the runtime's partial_cmp guard).
+    if (!(value > 0))
+        return requiredApprovals;
+    let raw;
+    if (type === 'percentage') {
+        if (participantCount === 0)
+            return null;
+        if (Number.isInteger(value)) {
+            const required = (BigInt(value) * BigInt(participantCount) + 99n) / 100n;
+            return Number(required > BigInt(U32_MAX) ? BigInt(U32_MAX) : required < 1n ? 1n : required);
+        }
+        raw = (value * participantCount) / 100;
+    }
+    else if (type === 'n_of_m' || type === 'count') {
+        raw = value;
+    }
+    else {
+        return null;
+    }
+    if (raw === Infinity)
+        return U32_MAX;
+    return Math.min(Math.max(1, Math.ceil(raw)), U32_MAX);
+}
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Uint8Array);
+}
+function isPolicyDescriptor(value) {
+    return isPlainRecord(value) && typeof value.policyId === 'string' && typeof value.rules === 'string';
+}
+function buildProposalPolicy(policyId, description, rules, options) {
+    checkEnum('acceptance.criterion', rules.acceptance?.criterion ?? 'all_parties', exports.PROPOSAL_ACCEPTANCE_CRITERIA);
+    checkMinInt('counter_proposal.max_rounds', rules.counterProposal?.maxRounds ?? 0, 0);
     const rulesJson = {
         acceptance: {
             criterion: rules.acceptance?.criterion ?? 'all_parties',
@@ -218,6 +419,7 @@ function buildProposalPolicy(policyId, description, rules) {
         },
         commitment: serializeCommitment(rules.commitment),
     };
+    addExtraKeys(rulesJson, options);
     return {
         policyId,
         mode: 'macp.mode.proposal.v1',
@@ -226,7 +428,7 @@ function buildProposalPolicy(policyId, description, rules) {
         schemaVersion: 1,
     };
 }
-function buildTaskPolicy(policyId, description, rules) {
+function buildTaskPolicy(policyId, description, rules, options) {
     const rulesJson = {
         assignment: {
             allow_reassignment_on_reject: rules.assignment?.allowReassignmentOnReject ?? false,
@@ -236,6 +438,7 @@ function buildTaskPolicy(policyId, description, rules) {
         },
         commitment: serializeCommitment(rules.commitment),
     };
+    addExtraKeys(rulesJson, options);
     return {
         policyId,
         mode: 'macp.mode.task.v1',
@@ -244,13 +447,15 @@ function buildTaskPolicy(policyId, description, rules) {
         schemaVersion: 1,
     };
 }
-function buildHandoffPolicy(policyId, description, rules) {
+function buildHandoffPolicy(policyId, description, rules, options) {
+    checkMinInt('acceptance.implicit_accept_timeout_ms', rules.acceptance?.implicitAcceptTimeoutMs ?? 0, 0);
     const rulesJson = {
         acceptance: {
             implicit_accept_timeout_ms: rules.acceptance?.implicitAcceptTimeoutMs ?? 0,
         },
         commitment: serializeCommitment(rules.commitment),
     };
+    addExtraKeys(rulesJson, options);
     return {
         policyId,
         mode: 'macp.mode.handoff.v1',

package/dist/projections/handoff.d.ts

@@ -36,4 +36,17 @@ export declare class HandoffProjection extends BaseProjection {
     pendingHandoffs(): HandoffRecord[];
     hasAcceptedOffer(handoffId?: string): boolean;
     activeOffer(): HandoffRecord | undefined;
+    /**
+     * Targets that declined an offer this session, in offer order, de-duplicated.
+     * Keyed on the offer's `targetParticipant` (as the runtime is), not on the
+     * payload-supplied `declinedBy`, which may be empty.
+     */
+    declinedTargets(): string[];
+    /**
+     * True if a new `HandoffOffer` to `target` would be admissible: `target` has
+     * not declined earlier in the session (rule 3a), no offer is outstanding,
+     * and no offer has been accepted. Does not check that `target` is a declared
+     * participant other than the sender.
+     */
+    canOfferTo(target: string): boolean;
 }

package/dist/projections/handoff.js

@@ -162,5 +162,32 @@ class HandoffProjection extends base_1.BaseProjection {
         }
         return undefined;
     }
+    // Advisory (RFC-MACP-0010 §5 rule 3a, runtime ≥ 0.9.0): modelled from what
+    // this projection has seen. A projection that joined mid-session may miss
+    // earlier offers, and sessions started on a runtime < 0.9.0 do not enforce
+    // rule 3a. Nothing refuses client-side — `HandoffSession.offer()` still
+    // sends, and the runtime's `INVALID_ENVELOPE` NACK is authoritative. Same
+    // names and semantics as macp-sdk-python's `HandoffProjection`.
+    /**
+     * Targets that declined an offer this session, in offer order, de-duplicated.
+     * Keyed on the offer's `targetParticipant` (as the runtime is), not on the
+     * payload-supplied `declinedBy`, which may be empty.
+     */
+    declinedTargets() {
+        return [
+            ...new Set([...this.handoffs.values()].filter((h) => h.status === 'declined').map((h) => h.targetParticipant)),
+        ];
+    }
+    /**
+     * True if a new `HandoffOffer` to `target` would be admissible: `target` has
+     * not declined earlier in the session (rule 3a), no offer is outstanding,
+     * and no offer has been accepted. Does not check that `target` is a declared
+     * participant other than the sender.
+     */
+    canOfferTo(target) {
+        if (this.declinedTargets().includes(target))
+            return false;
+        return ![...this.handoffs.values()].some((h) => h.status === 'offered' || h.status === 'context_sent' || h.status === 'accepted');
+    }
 }
 exports.HandoffProjection = HandoffProjection;

package/dist/projections/quorum.d.ts

@@ -14,6 +14,15 @@ export interface BallotRecord {
     reason?: string;
     sender: string;
 }
+/**
+ * Optional policy override for the `QuorumProjection` readiness helpers.
+ * `effectiveThreshold` is `effectiveQuorumThreshold()`'s result: a number
+ * replaces the payload's `requiredApprovals`, `null` means unsatisfiable
+ * (treated as an infinite bar), and omitting it keeps the payload value.
+ */
+export interface QuorumThresholdOptions {
+    effectiveThreshold?: number | null;
+}
 export declare class QuorumProjection extends BaseProjection {
     protected readonly mode = "macp.mode.quorum.v1";
     readonly requests: Map<string, ApprovalRequestRecord>;
@@ -25,11 +34,29 @@ export declare class QuorumProjection extends BaseProjection {
     approvalCount(requestId: string): number;
     rejectionCount(requestId: string): number;
     abstentionCount(requestId: string): number;
-    hasQuorum(requestId: string): boolean;
-    threshold(requestId: string): number;
+    /**
+     * The approval bar for `requestId`: the policy override when one is passed,
+     * else the payload's `requiredApprovals`. `null` (an unsatisfiable override,
+     * see `effectiveQuorumThreshold`) is an infinite bar. `undefined` for an
+     * unknown request.
+     */
+    private required;
+    /**
+     * True once the approval count reaches the bar. Pass `{ effectiveThreshold }`
+     * (from `effectiveQuorumThreshold`) when a bound policy's `threshold`
+     * overrides `requiredApprovals` (runtime ≥ 0.9.0, RFC-MACP-0011 §5 rule 6).
+     */
+    hasQuorum(requestId: string, options?: QuorumThresholdOptions): boolean;
+    /** The approval bar, or 0 if the request is unknown. `Infinity` for an unsatisfiable override. */
+    threshold(requestId: string, options?: QuorumThresholdOptions): number;
     votedSenders(requestId: string): string[];
-    remainingVotesNeeded(requestId: string): number;
-    commitmentReady(requestId: string): boolean;
-    isThresholdUnreachable(requestId: string, totalEligible: number): boolean;
+    remainingVotesNeeded(requestId: string, options?: QuorumThresholdOptions): number;
+    commitmentReady(requestId: string, options?: QuorumThresholdOptions): boolean;
+    /**
+     * True if the remaining possible approvals cannot reach the bar. Under a
+     * policy `threshold` override above the participant count (runtime ≥ 0.9.0)
+     * this is true before any ballot — pass `{ effectiveThreshold }` to see it.
+     */
+    isThresholdUnreachable(requestId: string, totalEligible: number, options?: QuorumThresholdOptions): boolean;
     private countVotes;
 }

package/dist/projections/quorum.js

@@ -95,34 +95,60 @@ class QuorumProjection extends base_1.BaseProjection {
     abstentionCount(requestId) {
         return this.countVotes(requestId, 'abstain');
     }
-    hasQuorum(requestId) {
+    /**
+     * The approval bar for `requestId`: the policy override when one is passed,
+     * else the payload's `requiredApprovals`. `null` (an unsatisfiable override,
+     * see `effectiveQuorumThreshold`) is an infinite bar. `undefined` for an
+     * unknown request.
+     */
+    required(requestId, options) {
         const req = this.requests.get(requestId);
         if (!req)
+            return undefined;
+        const override = options?.effectiveThreshold;
+        if (override === undefined)
+            return req.requiredApprovals;
+        return override === null ? Infinity : override;
+    }
+    /**
+     * True once the approval count reaches the bar. Pass `{ effectiveThreshold }`
+     * (from `effectiveQuorumThreshold`) when a bound policy's `threshold`
+     * overrides `requiredApprovals` (runtime ≥ 0.9.0, RFC-MACP-0011 §5 rule 6).
+     */
+    hasQuorum(requestId, options) {
+        const required = this.required(requestId, options);
+        if (required === undefined)
             return false;
-        return this.approvalCount(requestId) >= req.requiredApprovals;
+        return this.approvalCount(requestId) >= required;
     }
-    threshold(requestId) {
-        return this.requests.get(requestId)?.requiredApprovals ?? 0;
+    /** The approval bar, or 0 if the request is unknown. `Infinity` for an unsatisfiable override. */
+    threshold(requestId, options) {
+        return this.required(requestId, options) ?? 0;
     }
     votedSenders(requestId) {
         const senderMap = this.ballots.get(requestId);
         return senderMap ? [...senderMap.keys()] : [];
     }
-    remainingVotesNeeded(requestId) {
-        const req = this.requests.get(requestId);
-        if (!req)
+    remainingVotesNeeded(requestId, options) {
+        const required = this.required(requestId, options);
+        if (required === undefined)
             return 0;
-        return Math.max(0, req.requiredApprovals - this.approvalCount(requestId));
+        return Math.max(0, required - this.approvalCount(requestId));
     }
-    commitmentReady(requestId) {
-        return this.hasQuorum(requestId) && this.phase !== 'Committed';
+    commitmentReady(requestId, options) {
+        return this.hasQuorum(requestId, options) && this.phase !== 'Committed';
     }
-    isThresholdUnreachable(requestId, totalEligible) {
-        const req = this.requests.get(requestId);
-        if (!req)
+    /**
+     * True if the remaining possible approvals cannot reach the bar. Under a
+     * policy `threshold` override above the participant count (runtime ≥ 0.9.0)
+     * this is true before any ballot — pass `{ effectiveThreshold }` to see it.
+     */
+    isThresholdUnreachable(requestId, totalEligible, options) {
+        const required = this.required(requestId, options);
+        if (required === undefined)
             return false;
         const remaining = totalEligible - this.votedSenders(requestId).length;
-        return this.approvalCount(requestId) + remaining < req.requiredApprovals;
+        return this.approvalCount(requestId) + remaining < required;
     }
     countVotes(requestId, vote) {
         const senderMap = this.ballots.get(requestId);

package/dist/projections/task.d.ts

@@ -38,6 +38,13 @@ export interface TaskRejectRecord {
     assignee: string;
     reason?: string;
     sender: string;
+    /**
+     * `true` when the rejecter held the session's active assignment (RFC-MACP-0009
+     * §5 rule 3c: the assignee gave the task back). `false` for a pre-assignment
+     * personal decline (rule 2a, runtime ≥ 0.9.0), which leaves the task open to
+     * the other participants. Mirrors the runtime's `TaskRejectRecord.while_assigned`.
+     */
+    whileAssigned: boolean;
 }
 export declare class TaskProjection extends BaseProjection {
     protected readonly mode = "macp.mode.task.v1";
@@ -77,4 +84,22 @@ export declare class TaskProjection extends BaseProjection {
     activeTasks(): TaskRecord[];
     isAccepted(taskId: string): boolean;
     latestProgress(): number | undefined;
+    /** True if `participant` has sent a `TaskReject` (either kind). */
+    hasDeclined(participant: string): boolean;
+    /** Participants that sent a `TaskReject`, in arrival order, de-duplicated. */
+    declinedParticipants(): string[];
+    /**
+     * True if `participant` may still send `TaskAccept`: the session's assignee
+     * slot is free and `participant` has not declined (rule 2a). Does not
+     * evaluate the bound policy's `allow_reassignment_on_reject`, which the
+     * runtime also requires after an active assignee gave the task back.
+     */
+    canAccept(participant: string): boolean;
+    /**
+     * True if a negative Commitment is eligible for `taskId`: a terminal report
+     * (`TaskComplete`/`TaskFail`) exists, or the named `requestedAssignee`
+     * declined before accepting and no one holds the slot (rule 2a), leaving no
+     * eligible assignee.
+     */
+    negativeCommitEligible(taskId: string): boolean;
 }

package/dist/projections/task.js

@@ -119,9 +119,17 @@ class TaskProjection extends base_1.BaseProjection {
                 // `p.assignee or envelope.sender` does: TaskComplete/TaskFail below
                 // spread the payload's `assignee` as-is with no such fallback, and
                 // intra-SDK consistency wins over replicating Python's nuance here.
-                this.rejections.push({ ...record, sender: envelope.sender });
+                //
+                // `whileAssigned` is computed before the slot is freed (runtime
+                // `task.rs`, same order). Only the active assignee's reject (rule 3c)
+                // marks the task 'rejected'; a pre-assignment reject is a personal
+                // decline (RFC-MACP-0009 §5 rule 2a, runtime ≥ 0.9.0) that leaves the
+                // task 'requested' for everyone else.
+                const slot = this.activeAssignment;
+                const whileAssigned = slot?.sender === envelope.sender;
+                this.rejections.push({ ...record, sender: envelope.sender, whileAssigned });
                 const task = this.tasks.get(record.taskId);
-                if (task)
+                if (task && whileAssigned)
                     task.status = 'rejected';
                 // RFC-MACP-0009 §5 rule 3c (`:72`): "When policy sets
                 // `allow_reassignment_on_reject: true` and the active assignee sends
@@ -144,8 +152,8 @@ class TaskProjection extends base_1.BaseProjection {
                 // cannot diverge from the runtime on any real transcript, and it needs
                 // no new API surface (threading a `PolicyDefinition` into the
                 // constructor would). Issue #70, option 2.
-                if (this.activeAssignment?.sender === envelope.sender) {
-                    const held = this.tasks.get(this.activeAssignment.taskId);
+                if (slot && whileAssigned) {
+                    const held = this.tasks.get(slot.taskId);
                     if (held)
                         held.assignee = undefined;
                     this.activeAssignment = undefined;
@@ -213,5 +221,56 @@ class TaskProjection extends base_1.BaseProjection {
     latestProgress() {
         return this.updates[this.updates.length - 1]?.progress;
     }
+    // Advisory: the helpers below model the runtime's rev-4 rules (RFC-MACP-0009
+    // §5 rule 2a, runtime ≥ 0.9.0) from what this projection has seen. A
+    // projection that joined mid-session may be partial, and sessions started on
+    // a runtime < 0.9.0 keep the earlier rule (any prior reject gates every later
+    // accept). None of them refuse anything: `TaskSession.acceptTask()` still
+    // sends, and the runtime's NACK stays authoritative. Same names and semantics
+    // as macp-sdk-python's `TaskProjection`.
+    /** True if `participant` has sent a `TaskReject` (either kind). */
+    hasDeclined(participant) {
+        return this.rejections.some((r) => rejecterOf(r) === participant);
+    }
+    /** Participants that sent a `TaskReject`, in arrival order, de-duplicated. */
+    declinedParticipants() {
+        return [...new Set(this.rejections.map(rejecterOf))];
+    }
+    /**
+     * True if `participant` may still send `TaskAccept`: the session's assignee
+     * slot is free and `participant` has not declined (rule 2a). Does not
+     * evaluate the bound policy's `allow_reassignment_on_reject`, which the
+     * runtime also requires after an active assignee gave the task back.
+     */
+    canAccept(participant) {
+        return this.activeAssignment === undefined && !this.hasDeclined(participant);
+    }
+    /**
+     * True if a negative Commitment is eligible for `taskId`: a terminal report
+     * (`TaskComplete`/`TaskFail`) exists, or the named `requestedAssignee`
+     * declined before accepting and no one holds the slot (rule 2a), leaving no
+     * eligible assignee.
+     */
+    negativeCommitEligible(taskId) {
+        const task = this.tasks.get(taskId);
+        if (!task)
+            return false;
+        if (this.completions.some((c) => c.taskId === taskId) || this.failures.some((f) => f.taskId === taskId)) {
+            return true;
+        }
+        const requested = task.requestedAssignee;
+        return (!!requested &&
+            this.activeAssignment === undefined &&
+            this.rejections.some((r) => rejecterOf(r) === requested && !r.whileAssigned));
+    }
 }
 exports.TaskProjection = TaskProjection;
+/**
+ * Who a rejection is about: the payload's `assignee`, falling back to the
+ * envelope sender when the payload leaves it empty (Python's
+ * `p.assignee or envelope.sender`). Applied here, not to the stored record, so
+ * `TaskRejectRecord.assignee` keeps its as-sent value like TaskComplete/TaskFail.
+ */
+function rejecterOf(r) {
+    return r.assignee || r.sender;
+}

package/dist/types.d.ts

@@ -86,6 +86,21 @@ export interface AgentManifest {
     metadata?: Record<string, string>;
     transportEndpoints?: TransportEndpoint[];
 }
+/**
+ * `capabilities.policyRegistry` (`macp.v1.PolicyRegistryCapability`) as
+ * `InitializeResult.capabilities` carries it.
+ */
+export interface PolicyRegistryCapability {
+    registerPolicy?: boolean;
+    listPolicies?: boolean;
+    listChanged?: boolean;
+    /**
+     * Vendor-extension keys (RFC-MACP-0012 §4) this runtime implements, by full
+     * key name. Any other `x-` key is refused at RegisterPolicy. Advisory:
+     * admission, not this list, is authoritative. Runtime ≥ 0.9.0.
+     */
+    ruleExtensions?: string[];
+}
 export interface InitializeResult {
     selectedProtocolVersion: string;
     runtimeInfo?: {

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.16.1";
+export declare const VERSION = "0.17.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.16.1'; // x-release-please-version
+exports.VERSION = '0.17.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macp-sdk-typescript",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "TypeScript SDK for the MACP Rust runtime",
   "license": "Apache-2.0",
   "type": "commonjs",