macp-sdk-typescript 0.2.0

package/dist/policy.d.ts

@@ -0,0 +1,76 @@
+import type { PolicyDescriptor } from './types';
+export interface CommitmentRulesInput {
+    authority?: 'initiator_only' | 'any_participant' | 'designated_role';
+    designatedRoles?: string[];
+}
+export interface DecisionVotingRules {
+    algorithm?: 'none' | 'majority' | 'supermajority' | 'unanimous' | 'weighted' | 'plurality';
+    threshold?: number;
+    quorum?: {
+        type: 'count' | 'percentage';
+        value: number;
+    };
+    weights?: Record<string, number>;
+}
+export interface DecisionObjectionHandling {
+    criticalSeverityVetoes?: boolean;
+    vetoThreshold?: number;
+}
+export interface DecisionEvaluationRules {
+    minimumConfidence?: number;
+    requiredBeforeVoting?: boolean;
+}
+export interface DecisionCommitmentRules {
+    authority?: 'initiator_only' | 'any_participant' | 'designated_role';
+    designatedRoles?: string[];
+    requireVoteQuorum?: boolean;
+}
+export interface DecisionPolicyRulesInput {
+    voting?: DecisionVotingRules;
+    objectionHandling?: DecisionObjectionHandling;
+    evaluation?: DecisionEvaluationRules;
+    commitment?: DecisionCommitmentRules;
+}
+export interface QuorumPolicyRulesInput {
+    threshold?: {
+        type: 'n_of_m' | 'percentage' | 'weighted';
+        value: number;
+    };
+    abstention?: {
+        countsTowardQuorum?: boolean;
+        interpretation?: 'neutral' | 'implicit_reject' | 'ignored';
+    };
+    commitment?: CommitmentRulesInput;
+}
+export interface ProposalPolicyRulesInput {
+    acceptance?: {
+        criterion?: 'all_parties' | 'counterparty' | 'initiator';
+    };
+    counterProposal?: {
+        maxRounds?: number;
+    };
+    rejection?: {
+        terminalOnAnyReject?: boolean;
+    };
+    commitment?: CommitmentRulesInput;
+}
+export interface TaskPolicyRulesInput {
+    assignment?: {
+        allowReassignmentOnReject?: boolean;
+    };
+    completion?: {
+        requireOutput?: boolean;
+    };
+    commitment?: CommitmentRulesInput;
+}
+export interface HandoffPolicyRulesInput {
+    acceptance?: {
+        implicitAcceptTimeoutMs?: number;
+    };
+    commitment?: CommitmentRulesInput;
+}
+export declare function buildDecisionPolicy(policyId: string, description: string, rules: DecisionPolicyRulesInput): 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;

package/dist/policy.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDecisionPolicy = buildDecisionPolicy;
+exports.buildQuorumPolicy = buildQuorumPolicy;
+exports.buildProposalPolicy = buildProposalPolicy;
+exports.buildTaskPolicy = buildTaskPolicy;
+exports.buildHandoffPolicy = buildHandoffPolicy;
+function serializeCommitment(commitment) {
+    return {
+        authority: commitment?.authority ?? 'initiator_only',
+        designated_roles: commitment?.designatedRoles ?? [],
+    };
+}
+// ── Builder helpers ─────────────────────────────────────────────────
+function buildDecisionPolicy(policyId, description, rules) {
+    const rulesJson = {
+        voting: {
+            algorithm: rules.voting?.algorithm ?? 'none',
+            threshold: rules.voting?.threshold ?? 0.5,
+            quorum: rules.voting?.quorum ? { type: rules.voting.quorum.type, value: rules.voting.quorum.value } : undefined,
+            weights: rules.voting?.weights ?? undefined,
+        },
+        objection_handling: {
+            critical_severity_vetoes: rules.objectionHandling?.criticalSeverityVetoes ?? false,
+            veto_threshold: rules.objectionHandling?.vetoThreshold ?? 1,
+        },
+        evaluation: {
+            minimum_confidence: rules.evaluation?.minimumConfidence ?? 0,
+            required_before_voting: rules.evaluation?.requiredBeforeVoting ?? false,
+        },
+        commitment: {
+            authority: rules.commitment?.authority ?? 'initiator_only',
+            designated_roles: rules.commitment?.designatedRoles ?? [],
+            require_vote_quorum: rules.commitment?.requireVoteQuorum ?? false,
+        },
+    };
+    return {
+        policyId,
+        mode: 'macp.mode.decision.v1',
+        description,
+        rules: Buffer.from(JSON.stringify(rulesJson)),
+        schemaVersion: 1,
+    };
+}
+function buildQuorumPolicy(policyId, description, rules) {
+    const rulesJson = {
+        threshold: {
+            type: rules.threshold?.type ?? 'n_of_m',
+            value: rules.threshold?.value ?? 0,
+        },
+        abstention: {
+            counts_toward_quorum: rules.abstention?.countsTowardQuorum ?? false,
+            interpretation: rules.abstention?.interpretation ?? 'neutral',
+        },
+        commitment: serializeCommitment(rules.commitment),
+    };
+    return {
+        policyId,
+        mode: 'macp.mode.quorum.v1',
+        description,
+        rules: Buffer.from(JSON.stringify(rulesJson)),
+        schemaVersion: 1,
+    };
+}
+function buildProposalPolicy(policyId, description, rules) {
+    const rulesJson = {
+        acceptance: {
+            criterion: rules.acceptance?.criterion ?? 'all_parties',
+        },
+        counter_proposal: {
+            max_rounds: rules.counterProposal?.maxRounds ?? 0,
+        },
+        rejection: {
+            terminal_on_any_reject: rules.rejection?.terminalOnAnyReject ?? false,
+        },
+        commitment: serializeCommitment(rules.commitment),
+    };
+    return {
+        policyId,
+        mode: 'macp.mode.proposal.v1',
+        description,
+        rules: Buffer.from(JSON.stringify(rulesJson)),
+        schemaVersion: 1,
+    };
+}
+function buildTaskPolicy(policyId, description, rules) {
+    const rulesJson = {
+        assignment: {
+            allow_reassignment_on_reject: rules.assignment?.allowReassignmentOnReject ?? false,
+        },
+        completion: {
+            require_output: rules.completion?.requireOutput ?? false,
+        },
+        commitment: serializeCommitment(rules.commitment),
+    };
+    return {
+        policyId,
+        mode: 'macp.mode.task.v1',
+        description,
+        rules: Buffer.from(JSON.stringify(rulesJson)),
+        schemaVersion: 1,
+    };
+}
+function buildHandoffPolicy(policyId, description, rules) {
+    const rulesJson = {
+        acceptance: {
+            implicit_accept_timeout_ms: rules.acceptance?.implicitAcceptTimeoutMs ?? 0,
+        },
+        commitment: serializeCommitment(rules.commitment),
+    };
+    return {
+        policyId,
+        mode: 'macp.mode.handoff.v1',
+        description,
+        rules: Buffer.from(JSON.stringify(rulesJson)),
+        schemaVersion: 1,
+    };
+}

package/dist/projections/decision.d.ts

@@ -0,0 +1,49 @@
+import type { Envelope } from '../types';
+import type { ProtoRegistry } from '../proto-registry';
+export interface DecisionProposalRecord {
+    proposalId: string;
+    option: string;
+    rationale?: string;
+    sender: string;
+}
+export interface DecisionEvaluationRecord {
+    proposalId: string;
+    recommendation: string;
+    confidence: number;
+    reason?: string;
+    sender: string;
+}
+export interface DecisionObjectionRecord {
+    proposalId: string;
+    reason: string;
+    severity: string;
+    sender: string;
+}
+export interface DecisionVoteRecord {
+    proposalId: string;
+    vote: string;
+    reason?: string;
+    sender: string;
+}
+export declare class DecisionProjection {
+    readonly proposals: Map<string, DecisionProposalRecord>;
+    readonly evaluations: DecisionEvaluationRecord[];
+    readonly objections: DecisionObjectionRecord[];
+    readonly votes: Map<string, Map<string, DecisionVoteRecord>>;
+    readonly transcript: Envelope[];
+    phase: 'Proposal' | 'Evaluation' | 'Voting' | 'Committed';
+    commitment?: Record<string, unknown>;
+    applyEnvelope(envelope: Envelope, protoRegistry: ProtoRegistry): void;
+    get isCommitted(): boolean;
+    get isPositiveOutcome(): boolean | undefined;
+    voteTotals(): Record<string, number>;
+    majorityWinner(): string | undefined;
+    /** Returns the APPROVE vote ratio excluding ABSTAIN votes from the denominator. */
+    voteRatio(proposalId: string): number;
+    /** Only critical-severity objections are blocking per RFC-MACP-0004. */
+    hasBlockingObjection(proposalId?: string): boolean;
+    /** Evaluations with REVIEW recommendation (informational only). */
+    reviewEvaluations(): DecisionEvaluationRecord[];
+    /** Evaluations excluding REVIEW (qualifying evaluations). */
+    qualifyingEvaluations(): DecisionEvaluationRecord[];
+}

package/dist/projections/decision.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DecisionProjection = void 0;
+const constants_1 = require("../constants");
+class DecisionProjection {
+    proposals = new Map();
+    evaluations = [];
+    objections = [];
+    votes = new Map();
+    transcript = [];
+    phase = 'Proposal';
+    commitment;
+    applyEnvelope(envelope, protoRegistry) {
+        if (envelope.mode !== constants_1.MODE_DECISION)
+            return;
+        this.transcript.push(envelope);
+        const payload = protoRegistry.decodeKnownPayload(envelope.mode, envelope.messageType, envelope.payload);
+        switch (envelope.messageType) {
+            case 'Proposal': {
+                const record = payload;
+                this.proposals.set(record.proposalId, {
+                    proposalId: record.proposalId,
+                    option: record.option,
+                    rationale: record.rationale,
+                    sender: envelope.sender,
+                });
+                this.phase = 'Evaluation';
+                break;
+            }
+            case 'Evaluation': {
+                const record = payload;
+                this.evaluations.push({ ...record, sender: envelope.sender });
+                break;
+            }
+            case 'Objection': {
+                const record = payload;
+                this.objections.push({ ...record, severity: record.severity ?? 'medium', sender: envelope.sender });
+                break;
+            }
+            case 'Vote': {
+                const record = payload;
+                const bySender = this.votes.get(record.proposalId) ?? new Map();
+                bySender.set(envelope.sender, { ...record, sender: envelope.sender });
+                this.votes.set(record.proposalId, bySender);
+                this.phase = 'Voting';
+                break;
+            }
+            case 'Commitment': {
+                this.commitment = payload;
+                this.phase = 'Committed';
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    get isCommitted() {
+        return this.commitment !== undefined;
+    }
+    get isPositiveOutcome() {
+        if (!this.commitment)
+            return undefined;
+        const val = this.commitment.outcomePositive ??
+            this.commitment.outcome_positive;
+        return val !== undefined ? Boolean(val) : true;
+    }
+    voteTotals() {
+        const totals = {};
+        for (const [proposalId, senderVotes] of this.votes.entries()) {
+            totals[proposalId] = [...senderVotes.values()].filter((item) => isPositiveVote(item.vote)).length;
+        }
+        return totals;
+    }
+    majorityWinner() {
+        const totals = this.voteTotals();
+        const entries = Object.entries(totals);
+        if (!entries.length)
+            return undefined;
+        // Count total non-abstain votes across all proposals
+        let nonAbstain = 0;
+        for (const senderVotes of this.votes.values()) {
+            for (const vote of senderVotes.values()) {
+                if (vote.vote.toUpperCase() !== 'ABSTAIN') {
+                    nonAbstain++;
+                }
+            }
+        }
+        if (nonAbstain === 0)
+            return undefined;
+        for (const [proposalId, count] of entries) {
+            if (count / nonAbstain > 0.5)
+                return proposalId;
+        }
+        return undefined;
+    }
+    /** Returns the APPROVE vote ratio excluding ABSTAIN votes from the denominator. */
+    voteRatio(proposalId) {
+        const senderVotes = this.votes.get(proposalId);
+        if (!senderVotes)
+            return 0;
+        const votes = [...senderVotes.values()];
+        const nonAbstain = votes.filter((v) => v.vote.toUpperCase() !== 'ABSTAIN');
+        if (nonAbstain.length === 0)
+            return 0;
+        const approvals = nonAbstain.filter((v) => isPositiveVote(v.vote)).length;
+        return approvals / nonAbstain.length;
+    }
+    /** Only critical-severity objections are blocking per RFC-MACP-0004. */
+    hasBlockingObjection(proposalId) {
+        if (proposalId !== undefined) {
+            return this.objections.some((item) => item.proposalId === proposalId && item.severity.toLowerCase() === 'critical');
+        }
+        return this.objections.some((item) => item.severity.toLowerCase() === 'critical');
+    }
+    /** Evaluations with REVIEW recommendation (informational only). */
+    reviewEvaluations() {
+        return this.evaluations.filter((e) => e.recommendation.toUpperCase() === 'REVIEW');
+    }
+    /** Evaluations excluding REVIEW (qualifying evaluations). */
+    qualifyingEvaluations() {
+        return this.evaluations.filter((e) => e.recommendation.toUpperCase() !== 'REVIEW');
+    }
+}
+exports.DecisionProjection = DecisionProjection;
+function isPositiveVote(vote) {
+    const normalized = vote.trim().toUpperCase();
+    return (normalized === 'APPROVE' ||
+        normalized === 'APPROVED' ||
+        normalized === 'YES' ||
+        normalized === 'ACCEPT' ||
+        normalized === 'ACCEPTED');
+}

package/dist/projections/handoff.d.ts

@@ -0,0 +1,28 @@
+import type { Envelope } from '../types';
+import type { ProtoRegistry } from '../proto-registry';
+export interface HandoffRecord {
+    handoffId: string;
+    targetParticipant: string;
+    scope: string;
+    reason?: string;
+    sender: string;
+    status: 'offered' | 'context_sent' | 'accepted' | 'declined';
+    contextContentType?: string;
+    acceptedBy?: string;
+    declinedBy?: string;
+}
+export declare class HandoffProjection {
+    readonly handoffs: Map<string, HandoffRecord>;
+    readonly transcript: Envelope[];
+    phase: 'Pending' | 'OfferPending' | 'ContextSharing' | 'Accepted' | 'Declined' | 'Committed';
+    commitment?: Record<string, unknown>;
+    applyEnvelope(envelope: Envelope, protoRegistry: ProtoRegistry): void;
+    get isCommitted(): boolean;
+    get isPositiveOutcome(): boolean | undefined;
+    getHandoff(handoffId: string): HandoffRecord | undefined;
+    isAccepted(handoffId: string): boolean;
+    isDeclined(handoffId: string): boolean;
+    pendingHandoffs(): HandoffRecord[];
+    hasAcceptedOffer(handoffId?: string): boolean;
+    activeOffer(): HandoffRecord | undefined;
+}

package/dist/projections/handoff.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HandoffProjection = void 0;
+const constants_1 = require("../constants");
+class HandoffProjection {
+    handoffs = new Map();
+    transcript = [];
+    phase = 'Pending';
+    commitment;
+    applyEnvelope(envelope, protoRegistry) {
+        if (envelope.mode !== constants_1.MODE_HANDOFF)
+            return;
+        this.transcript.push(envelope);
+        const payload = protoRegistry.decodeKnownPayload(envelope.mode, envelope.messageType, envelope.payload);
+        switch (envelope.messageType) {
+            case 'HandoffOffer': {
+                const record = payload;
+                this.handoffs.set(record.handoffId, {
+                    handoffId: record.handoffId,
+                    targetParticipant: record.targetParticipant,
+                    scope: record.scope,
+                    reason: record.reason,
+                    sender: envelope.sender,
+                    status: 'offered',
+                });
+                this.phase = 'OfferPending';
+                break;
+            }
+            case 'HandoffContext': {
+                const record = payload;
+                const handoff = this.handoffs.get(record.handoffId);
+                if (handoff) {
+                    // Per RFC-MACP-0010 §2.1: context after accept is permitted as supplementary docs.
+                    // Only update status if not already accepted/declined.
+                    if (handoff.status === 'offered') {
+                        handoff.status = 'context_sent';
+                    }
+                    handoff.contextContentType = record.contentType;
+                }
+                if (this.phase === 'OfferPending')
+                    this.phase = 'ContextSharing';
+                break;
+            }
+            case 'HandoffAccept': {
+                const record = payload;
+                const handoff = this.handoffs.get(record.handoffId);
+                if (handoff) {
+                    handoff.status = 'accepted';
+                    handoff.acceptedBy = record.acceptedBy;
+                }
+                this.phase = 'Accepted';
+                break;
+            }
+            case 'HandoffDecline': {
+                const record = payload;
+                const handoff = this.handoffs.get(record.handoffId);
+                if (handoff) {
+                    handoff.status = 'declined';
+                    handoff.declinedBy = record.declinedBy;
+                }
+                this.phase = 'Declined';
+                break;
+            }
+            case 'Commitment': {
+                this.commitment = payload;
+                this.phase = 'Committed';
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    get isCommitted() {
+        return this.commitment !== undefined;
+    }
+    get isPositiveOutcome() {
+        if (!this.commitment)
+            return undefined;
+        const val = this.commitment.outcomePositive ??
+            this.commitment.outcome_positive;
+        return val !== undefined ? Boolean(val) : true;
+    }
+    getHandoff(handoffId) {
+        return this.handoffs.get(handoffId);
+    }
+    isAccepted(handoffId) {
+        return this.handoffs.get(handoffId)?.status === 'accepted';
+    }
+    isDeclined(handoffId) {
+        return this.handoffs.get(handoffId)?.status === 'declined';
+    }
+    pendingHandoffs() {
+        return [...this.handoffs.values()].filter((h) => h.status === 'offered' || h.status === 'context_sent');
+    }
+    hasAcceptedOffer(handoffId) {
+        if (handoffId)
+            return this.handoffs.get(handoffId)?.status === 'accepted';
+        return [...this.handoffs.values()].some((h) => h.status === 'accepted');
+    }
+    activeOffer() {
+        const all = [...this.handoffs.values()];
+        for (let i = all.length - 1; i >= 0; i--) {
+            const record = all[i];
+            if (record && (record.status === 'offered' || record.status === 'context_sent')) {
+                return record;
+            }
+        }
+        return undefined;
+    }
+}
+exports.HandoffProjection = HandoffProjection;

package/dist/projections/proposal.d.ts

@@ -0,0 +1,40 @@
+import type { Envelope } from '../types';
+import type { ProtoRegistry } from '../proto-registry';
+export interface ProposalRecord {
+    proposalId: string;
+    title: string;
+    summary?: string;
+    tags?: string[];
+    sender: string;
+    supersedes?: string;
+    status: 'open' | 'accepted' | 'rejected' | 'withdrawn';
+}
+export interface ProposalAcceptRecord {
+    proposalId: string;
+    reason?: string;
+    sender: string;
+}
+export interface ProposalRejectRecord {
+    proposalId: string;
+    terminal: boolean;
+    reason?: string;
+    sender: string;
+}
+export declare class ProposalProjection {
+    readonly proposals: Map<string, ProposalRecord>;
+    readonly accepts: ProposalAcceptRecord[];
+    readonly rejections: ProposalRejectRecord[];
+    readonly transcript: Envelope[];
+    phase: 'Negotiating' | 'TerminalRejected' | 'Committed';
+    commitment?: Record<string, unknown>;
+    applyEnvelope(envelope: Envelope, protoRegistry: ProtoRegistry): void;
+    get isCommitted(): boolean;
+    get isPositiveOutcome(): boolean | undefined;
+    activeProposals(): ProposalRecord[];
+    latestProposal(): ProposalRecord | undefined;
+    isAccepted(proposalId: string): boolean;
+    isTerminallyRejected(proposalId: string): boolean;
+    liveProposals(): Map<string, ProposalRecord>;
+    acceptedProposal(): string | undefined;
+    hasTerminalRejection(): boolean;
+}

package/dist/projections/proposal.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProposalProjection = void 0;
+const constants_1 = require("../constants");
+class ProposalProjection {
+    proposals = new Map();
+    accepts = [];
+    rejections = [];
+    transcript = [];
+    phase = 'Negotiating';
+    commitment;
+    applyEnvelope(envelope, protoRegistry) {
+        if (envelope.mode !== constants_1.MODE_PROPOSAL)
+            return;
+        this.transcript.push(envelope);
+        const payload = protoRegistry.decodeKnownPayload(envelope.mode, envelope.messageType, envelope.payload);
+        switch (envelope.messageType) {
+            case 'Proposal': {
+                const record = payload;
+                this.proposals.set(record.proposalId, {
+                    proposalId: record.proposalId,
+                    title: record.title,
+                    summary: record.summary,
+                    tags: record.tags,
+                    sender: envelope.sender,
+                    status: 'open',
+                });
+                break;
+            }
+            case 'CounterProposal': {
+                const record = payload;
+                this.proposals.set(record.proposalId, {
+                    proposalId: record.proposalId,
+                    title: record.title,
+                    summary: record.summary,
+                    sender: envelope.sender,
+                    supersedes: record.supersedesProposalId,
+                    status: 'open',
+                });
+                break;
+            }
+            case 'Accept': {
+                const record = payload;
+                this.accepts.push({ ...record, sender: envelope.sender });
+                break;
+            }
+            case 'Reject': {
+                const record = payload;
+                const terminal = record.terminal ?? false;
+                this.rejections.push({
+                    proposalId: record.proposalId,
+                    terminal,
+                    reason: record.reason,
+                    sender: envelope.sender,
+                });
+                if (terminal) {
+                    const proposal = this.proposals.get(record.proposalId);
+                    if (proposal)
+                        proposal.status = 'rejected';
+                    this.phase = 'TerminalRejected';
+                }
+                break;
+            }
+            case 'Withdraw': {
+                const record = payload;
+                const proposal = this.proposals.get(record.proposalId);
+                if (proposal)
+                    proposal.status = 'withdrawn';
+                break;
+            }
+            case 'Commitment': {
+                this.commitment = payload;
+                this.phase = 'Committed';
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    get isCommitted() {
+        return this.commitment !== undefined;
+    }
+    get isPositiveOutcome() {
+        if (!this.commitment)
+            return undefined;
+        const val = this.commitment.outcomePositive ??
+            this.commitment.outcome_positive;
+        return val !== undefined ? Boolean(val) : true;
+    }
+    activeProposals() {
+        return [...this.proposals.values()].filter((p) => p.status === 'open');
+    }
+    latestProposal() {
+        const all = [...this.proposals.values()];
+        return all[all.length - 1];
+    }
+    isAccepted(proposalId) {
+        return this.accepts.some((a) => a.proposalId === proposalId);
+    }
+    isTerminallyRejected(proposalId) {
+        return this.rejections.some((r) => r.proposalId === proposalId && r.terminal);
+    }
+    liveProposals() {
+        const result = new Map();
+        for (const [id, p] of this.proposals) {
+            if (p.status !== 'withdrawn')
+                result.set(id, p);
+        }
+        return result;
+    }
+    acceptedProposal() {
+        if (this.accepts.length === 0)
+            return undefined;
+        const ids = new Set(this.accepts.map((a) => a.proposalId));
+        if (ids.size === 1)
+            return ids.values().next().value;
+        return undefined;
+    }
+    hasTerminalRejection() {
+        return this.rejections.some((r) => r.terminal);
+    }
+}
+exports.ProposalProjection = ProposalProjection;