agent-passport-system 1.26.0 → 1.27.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/agent-passport-system)](https://www.npmjs.com/package/agent-passport-system)
 [![license](https://img.shields.io/npm/l/agent-passport-system)](https://github.com/aeoess/agent-passport-system/blob/main/LICENSE)
-[![tests](https://img.shields.io/badge/tests-1507%20passing-brightgreen)](https://github.com/aeoess/agent-passport-system)
+[![tests](https://img.shields.io/badge/tests-1557%20passing-brightgreen)](https://github.com/aeoess/agent-passport-system)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18749779.svg)](https://doi.org/10.5281/zenodo.18749779)
 
 > **For AI agents:** visit [aeoess.com/llms.txt](https://aeoess.com/llms.txt) for machine-readable docs or [llms-full.txt](https://aeoess.com/llms-full.txt) for the complete reference.
@@ -90,7 +90,7 @@ const agent = joinSocialContract({ name: 'my-agent', owner: 'alice', floor: floo
 
 ## The Stack
 
-42 core modules + 32 v2 constitutional modules. 1507 tests. Zero heavy dependencies.
+48 core modules + 32 v2 constitutional modules. 1557 tests. Zero heavy dependencies.
 
 | Layer | What it does | Key primitive |
 |-------|-------------|---------------|
@@ -109,7 +109,7 @@ const agent = joinSocialContract({ name: 'my-agent', owner: 'alice', floor: floo
 
 ## MCP Server
 
-108 tools across all modules. Any MCP client connects agents directly.
+120 tools across all modules. Any MCP client connects agents directly.
 
 ```bash
 npm install -g agent-passport-system-mcp
@@ -144,7 +144,7 @@ npx agent-passport audit --floor values/floor.yaml
 
 ```bash
 npm test
-# 1507 tests across 79 files, 392 suites, 0 failures
+# 1557 tests across 84 files, 405 suites, 0 failures
 ```
 
 50 adversarial tests: Merkle tampering, attribution gaming, compliance violations, floor negotiation attacks, cross-chain confused deputy, taint laundering, authority probing.
@@ -162,7 +162,7 @@ npm test
 | Signed receipts | 3-sig chain | Proposed | Logs | General | — |
 | Values enforcement | 8 principles, graduated | — | Rules | — | — |
 | Coordination | Task lifecycle + MCP | — | — | — | — |
-| Tests | 1507 (50 adversarial) | None | Limited | None | None |
+| Tests | 1557 (50 adversarial) | None | Limited | None | None |
 
 ## Recognition
 

package/dist/src/core/charter.d.ts

@@ -0,0 +1,91 @@
+import type { CharterCore, CharterSignature, Office, OfficeRegistry, OfficeTransfer, CharterAmendment, CharterVerification, AmendmentVerification, DelegationSurvival, DissolutionPolicy, DisputeVenue, SuccessionRule, SuccessionTrigger, QuorumFailurePolicy } from '../types/charter.js';
+import type { MultiClassThresholdPolicy, ApprovalRequest, ApprovalSignature, ApprovalSubjectType, ApprovalEvaluation, ApprovalPolicy } from '../types/approval.js';
+export interface CreateCharterOptions {
+    name: string;
+    offices: Office[];
+    amendmentPolicy: MultiClassThresholdPolicy;
+    dissolutionPolicy: DissolutionPolicy;
+    delegationSurvival: DelegationSurvival;
+    disputeVenue?: DisputeVenue;
+    founderPrivateKey: string;
+    founderPublicKey: string;
+    founderRole: string;
+    version?: string;
+}
+/** Create a new charter. The founder signs it as the first founding signatory.
+ *  Additional signatories can be added with signCharter() until the
+ *  amendment policy threshold is met. */
+export declare function createCharter(opts: CreateCharterOptions): CharterCore;
+/** Add a founding signature to a charter. Returns a new charter
+ *  with the additional signature and a re-signed outer signature. */
+export declare function signCharter(charter: CharterCore, signerPrivateKey: string, signerPublicKey: string, signerRole: string, resignerPrivateKey: string): CharterCore;
+/** Verify a charter's integrity: content hash, signatures, office consistency. */
+export declare function verifyCharter(charter: CharterCore): CharterVerification;
+/** Evaluate whether a set of signatures satisfies a multi-class threshold policy.
+ *  All class requirements must be met (conjunction). Consilium Q5. */
+export declare function evaluateThreshold(policy: MultiClassThresholdPolicy, signatures: ApprovalSignature[]): ApprovalEvaluation;
+export interface CreateAmendmentOptions {
+    charter: CharterCore;
+    proposedCharter: CharterCore;
+    description: string;
+    proposerPrivateKey: string;
+    proposerPublicKey: string;
+    effectiveAt?: string;
+}
+/** Create a charter amendment proposal. Does NOT apply it —
+ *  signatures must be collected and threshold evaluated first. */
+export declare function createAmendment(opts: CreateAmendmentOptions): CharterAmendment;
+/** Add a signature to a charter amendment. */
+export declare function signAmendment(amendment: CharterAmendment, signerPrivateKey: string, signerPublicKey: string, signerRole: string): CharterAmendment;
+/** Verify a charter amendment against the charter's amendment policy. */
+export declare function verifyAmendment(amendment: CharterAmendment, charter: CharterCore): AmendmentVerification;
+/** Create an OfficeRegistry from a charter's offices. */
+export declare function createOfficeRegistry(charter: CharterCore, successionRules: SuccessionRule[], quorumFailurePolicies: QuorumFailurePolicy[], signerPrivateKey: string): OfficeRegistry;
+export interface CreateOfficeTransferOptions {
+    charter: CharterCore;
+    officeId: string;
+    fromHolder: string | null;
+    toHolder: string | null;
+    trigger: SuccessionTrigger | 'appointment' | 'resignation';
+    delegationHandling: 'frozen' | 'transferred' | 'revoked';
+    approvalSignatures: CharterSignature[];
+    signerPrivateKey: string;
+}
+/** Record an office holder change. */
+export declare function createOfficeTransfer(opts: CreateOfficeTransferOptions): OfficeTransfer;
+/** Create an approval request for a multi-party action. */
+export declare function createApprovalRequest(policyId: string, subject: string, subjectType: ApprovalSubjectType, requestedBy: string, timeoutSeconds: number): ApprovalRequest;
+/** Add a signature to an approval request. Validates the signer
+ *  is not a duplicate and the request hasn't expired. */
+export declare function addApprovalSignature(request: ApprovalRequest, signerPrivateKey: string, signerPublicKey: string, keyClass: string, officeId?: string): ApprovalRequest;
+/** Evaluate an approval request against its policy. For 'threshold'
+ *  type, delegates to evaluateThreshold. For simpler types, does
+ *  direct checks. Returns the updated request with status. */
+export declare function evaluateApprovalRequest(request: ApprovalRequest, policy: ApprovalPolicy): {
+    request: ApprovalRequest;
+    evaluation: ApprovalEvaluation;
+};
+/** Find an office by ID within a charter. */
+export declare function findOffice(charter: CharterCore, officeId: string): Office | undefined;
+/** Find which office(s) a public key holds. */
+export declare function findOfficesByHolder(charter: CharterCore, publicKey: string): Office[];
+/** Resolve the successor office for a vacant office. Walks the
+ *  succession order and returns the first non-vacant office. */
+export declare function resolveSuccessor(charter: CharterCore, officeId: string): Office | null;
+/** Check if a holder can take an office without violating
+ *  incompatibility constraints (GPT #20). */
+export declare function checkIncompatibility(charter: CharterCore, officeId: string, holderPublicKey: string): {
+    compatible: boolean;
+    conflicts: string[];
+};
+/** Check if an office has quorum per its QuorumFailurePolicy. */
+export declare function checkQuorum(office: Office, policy: QuorumFailurePolicy | undefined): {
+    hasQuorum: boolean;
+    holders: number;
+    required: number;
+};
+/** Check if a charter is in dissolution grace period. */
+export declare function isInDissolutionGrace(charter: CharterCore): boolean;
+/** Verify an office transfer signature. */
+export declare function verifyOfficeTransfer(transfer: OfficeTransfer): boolean;
+//# sourceMappingURL=charter.d.ts.map

package/dist/src/core/charter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"charter.d.ts","sourceRoot":"","sources":["../../../src/core/charter.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,WAAW,EAAiB,gBAAgB,EAC5C,MAAM,EACN,cAAc,EAAE,cAAc,EAC9B,gBAAgB,EAAE,mBAAmB,EAAE,qBAAqB,EAC5D,kBAAkB,EAAE,iBAAiB,EAAE,YAAY,EACnD,cAAc,EAAE,iBAAiB,EAAE,mBAAmB,EACvD,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EACV,yBAAyB,EACzB,eAAe,EAAE,iBAAiB,EAAE,mBAAmB,EACvD,kBAAkB,EAAkB,cAAc,EACnD,MAAM,sBAAsB,CAAA;AAc7B,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,eAAe,EAAE,yBAAyB,CAAA;IAC1C,iBAAiB,EAAE,iBAAiB,CAAA;IACpC,kBAAkB,EAAE,kBAAkB,CAAA;IACtC,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,iBAAiB,EAAE,MAAM,CAAA;IACzB,gBAAgB,EAAE,MAAM,CAAA;IACxB,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;yCAEyC;AACzC,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,WAAW,CA2CrE;AAMD;qEACqE;AACrE,wBAAgB,WAAW,CACzB,OAAO,EAAE,WAAW,EACpB,gBAAgB,EAAE,MAAM,EACxB,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,EAClB,kBAAkB,EAAE,MAAM,GACzB,WAAW,CAoBb;AAMD,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,mBAAmB,CAkFvE;AAMD;sEACsE;AACtE,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,yBAAyB,EACjC,UAAU,EAAE,iBAAiB,EAAE,GAC9B,kBAAkB,CAsCpB;AAMD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,WAAW,CAAA;IACpB,eAAe,EAAE,WAAW,CAAA;IAC5B,WAAW,EAAE,MAAM,CAAA;IACnB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,iBAAiB,EAAE,MAAM,CAAA;IACzB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;kEACkE;AAClE,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,gBAAgB,CAgC9E;AAED,8CAA8C;AAC9C,wBAAgB,aAAa,CAC3B,SAAS,EAAE,gBAAgB,EAC3B,gBAAgB,EAAE,MAAM,EACxB,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,GACjB,gBAAgB,CAalB;AAMD,yEAAyE;AACzE,wBAAgB,eAAe,CAC7B,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,WAAW,GACnB,qBAAqB,CA2DvB;AAMD,yDAAyD;AACzD,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,WAAW,EACpB,eAAe,EAAE,cAAc,EAAE,EACjC,qBAAqB,EAAE,mBAAmB,EAAE,EAC5C,gBAAgB,EAAE,MAAM,GACvB,cAAc,CAahB;AAMD,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,WAAW,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,OAAO,EAAE,iBAAiB,GAAG,aAAa,GAAG,aAAa,CAAA;IAC1D,kBAAkB,EAAE,QAAQ,GAAG,aAAa,GAAG,SAAS,CAAA;IACxD,kBAAkB,EAAE,gBAAgB,EAAE,CAAA;IACtC,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,sCAAsC;AACtC,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,2BAA2B,GAAG,cAAc,CAmBtF;AAMD,2DAA2D;AAC3D,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,mBAAmB,EAChC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,GACrB,eAAe,CAejB;AAED;yDACyD;AACzD,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,eAAe,EACxB,gBAAgB,EAAE,MAAM,EACxB,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,GAChB,eAAe,CAwBjB;AAED;;8DAE8D;AAC9D,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,cAAc,GACrB;IAAE,OAAO,EAAE,eAAe,CAAC;IAAC,UAAU,EAAE,kBAAkB,CAAA;CAAE,CAiF9D;AAMD,6CAA6C;AAC7C,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAErF;AAED,+CAA+C;AAC/C,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAIrF;AAED;gEACgE;AAChE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWtF;AAED;6CAC6C;AAC7C,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACtB;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAwB9C;AAED,iEAAiE;AACjE,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,mBAAmB,GAAG,SAAS,GACtC;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAQ3D;AAED,yDAAyD;AACzD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAElE;AAED,2CAA2C;AAC3C,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAStE"}

package/dist/src/core/charter.js

@@ -0,0 +1,536 @@
+// Copyright 2024-2026 Tymofii Pidlisnyi. Apache-2.0 license. See LICENSE.
+// ══════════════════════════════════════════════════════════════════
+// Charter — Pure Functions for Institutional Governance
+// ══════════════════════════════════════════════════════════════════
+// Create, verify, amend charters. Evaluate multi-class thresholds.
+// Manage office transfers and succession. All functions are pure —
+// no side effects, no storage, no gateway calls.
+// ══════════════════════════════════════════════════════════════════
+import { v4 as uuidv4 } from 'uuid';
+import { sign, verify } from '../crypto/keys.js';
+import { canonicalize } from './canonical.js';
+import { createHash } from 'crypto';
+// ══════════════════════════════════════
+// CONTENT HASHING
+// ══════════════════════════════════════
+function charterHash(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+/** Create a new charter. The founder signs it as the first founding signatory.
+ *  Additional signatories can be added with signCharter() until the
+ *  amendment policy threshold is met. */
+export function createCharter(opts) {
+    const now = new Date().toISOString();
+    // Validate offices
+    const officeIds = opts.offices.map(o => o.officeId);
+    const duplicateOffice = officeIds.find((id, i) => officeIds.indexOf(id) !== i);
+    if (duplicateOffice) {
+        throw new Error(`Duplicate office ID: ${duplicateOffice}`);
+    }
+    // Build charter without signature first
+    const charter = {
+        charterId: 'charter_' + uuidv4().slice(0, 12),
+        version: opts.version ?? '1.0.0',
+        previousVersion: null,
+        name: opts.name,
+        status: 'active',
+        offices: opts.offices,
+        amendmentPolicy: opts.amendmentPolicy,
+        dissolutionPolicy: opts.dissolutionPolicy,
+        delegationSurvival: opts.delegationSurvival,
+        disputeVenue: opts.disputeVenue,
+        createdAt: now,
+        foundingSignatures: [],
+    };
+    // Hash the charter content
+    const contentHash = charterHash(canonicalize(charter));
+    // Founder signs the content hash
+    const founderSig = {
+        publicKey: opts.founderPublicKey,
+        role: opts.founderRole,
+        signedAt: now,
+        signature: sign(contentHash, opts.founderPrivateKey),
+    };
+    // Sign the full charter (content hash + founding signatures)
+    const withSigs = { ...charter, contentHash, foundingSignatures: [founderSig] };
+    const canonical = canonicalize(withSigs);
+    const signature = sign(canonical, opts.founderPrivateKey);
+    return { ...withSigs, signature };
+}
+// ══════════════════════════════════════
+// SIGN CHARTER (add founding signature)
+// ══════════════════════════════════════
+/** Add a founding signature to a charter. Returns a new charter
+ *  with the additional signature and a re-signed outer signature. */
+export function signCharter(charter, signerPrivateKey, signerPublicKey, signerRole, resignerPrivateKey) {
+    // Check for duplicate signer
+    if (charter.foundingSignatures.some(s => s.publicKey === signerPublicKey)) {
+        throw new Error(`Signer ${signerPublicKey.slice(0, 8)}... already signed this charter`);
+    }
+    const newSig = {
+        publicKey: signerPublicKey,
+        role: signerRole,
+        signedAt: new Date().toISOString(),
+        signature: sign(charter.contentHash, signerPrivateKey),
+    };
+    const updatedSigs = [...charter.foundingSignatures, newSig];
+    const withSigs = { ...charter, foundingSignatures: updatedSigs };
+    const { signature: _old, ...signable } = withSigs;
+    const canonical = canonicalize(signable);
+    const signature = sign(canonical, resignerPrivateKey);
+    return { ...withSigs, signature };
+}
+// ══════════════════════════════════════
+// VERIFY CHARTER
+// ══════════════════════════════════════
+/** Verify a charter's integrity: content hash, signatures, office consistency. */
+export function verifyCharter(charter) {
+    const errors = [];
+    // 1. Content integrity — strip signature + contentHash + foundingSignatures, re-hash
+    const { signature, contentHash, foundingSignatures, ...body } = charter;
+    const expectedHash = charterHash(canonicalize({ ...body, foundingSignatures: [] }));
+    const contentIntegrity = expectedHash === contentHash;
+    if (!contentIntegrity)
+        errors.push('Content hash mismatch');
+    // 2. Verify each founding signature against the content hash
+    let signaturesValid = true;
+    for (const sig of foundingSignatures) {
+        try {
+            if (!verify(contentHash, sig.signature, sig.publicKey)) {
+                signaturesValid = false;
+                errors.push(`Invalid signature from ${sig.publicKey.slice(0, 8)}...`);
+            }
+        }
+        catch {
+            signaturesValid = false;
+            errors.push(`Signature verification failed for ${sig.publicKey.slice(0, 8)}...`);
+        }
+    }
+    // 3. Check if founding signatures meet the amendment policy threshold
+    const quorumEval = evaluateThreshold(charter.amendmentPolicy, foundingSignatures.map(s => ({ publicKey: s.publicKey, keyClass: s.role, signedAt: s.signedAt, signature: s.signature })));
+    const quorumMet = quorumEval.met;
+    if (!quorumMet)
+        errors.push('Founding signatures do not meet amendment policy threshold');
+    // 4. Not dissolved
+    const notDissolved = charter.status !== 'dissolved';
+    if (!notDissolved)
+        errors.push('Charter has been dissolved');
+    // 5. Office validation — no duplicate IDs, succession references valid offices
+    let officesValid = true;
+    const officeIds = new Set(charter.offices.map(o => o.officeId));
+    for (const office of charter.offices) {
+        for (const succId of office.successionOrder) {
+            if (!officeIds.has(succId)) {
+                officesValid = false;
+                errors.push(`Office ${office.officeId} succession references unknown office ${succId}`);
+            }
+        }
+    }
+    // 6. Incompatibility — no holder holds two incompatible offices (GPT #20)
+    let incompatibilityClean = true;
+    const holderOffices = new Map();
+    for (const office of charter.offices) {
+        for (const holder of office.holderSet) {
+            const existing = holderOffices.get(holder.publicKey) ?? [];
+            existing.push(office.officeId);
+            holderOffices.set(holder.publicKey, existing);
+        }
+    }
+    for (const office of charter.offices) {
+        if (!office.incompatibleOffices?.length)
+            continue;
+        for (const holder of office.holderSet) {
+            const held = holderOffices.get(holder.publicKey) ?? [];
+            for (const incomp of office.incompatibleOffices) {
+                if (held.includes(incomp)) {
+                    incompatibilityClean = false;
+                    errors.push(`Holder ${holder.publicKey.slice(0, 8)}... holds incompatible offices: ${office.officeId} and ${incomp}`);
+                }
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        contentIntegrity,
+        signaturesValid,
+        quorumMet,
+        notDissolved,
+        officesValid,
+        incompatibilityClean,
+    };
+}
+// ══════════════════════════════════════
+// EVALUATE MULTI-CLASS THRESHOLD
+// ══════════════════════════════════════
+/** Evaluate whether a set of signatures satisfies a multi-class threshold policy.
+ *  All class requirements must be met (conjunction). Consilium Q5. */
+export function evaluateThreshold(policy, signatures) {
+    const errors = [];
+    const classStatus = [];
+    let totalValid = 0;
+    let totalRequired = 0;
+    for (const req of policy.requirements) {
+        // Count valid signatures for this class
+        const validSigs = signatures.filter(s => s.keyClass === req.role && req.eligibleKeys.includes(s.publicKey));
+        // Deduplicate — same key signing twice doesn't count twice
+        const uniqueSigners = new Set(validSigs.map(s => s.publicKey));
+        const collected = uniqueSigners.size;
+        const satisfied = collected >= req.requiredSignatures;
+        if (!satisfied) {
+            errors.push(`Class '${req.role}': ${collected}/${req.requiredSignatures} signatures`);
+        }
+        classStatus.push({
+            role: req.role,
+            required: req.requiredSignatures,
+            collected,
+            satisfied,
+        });
+        totalValid += collected;
+        totalRequired += req.requiredSignatures;
+    }
+    return {
+        met: errors.length === 0,
+        classStatus,
+        totalValidSignatures: totalValid,
+        totalRequired,
+        expired: false, // caller must check timeout externally
+        errors,
+    };
+}
+/** Create a charter amendment proposal. Does NOT apply it —
+ *  signatures must be collected and threshold evaluated first. */
+export function createAmendment(opts) {
+    const now = new Date().toISOString();
+    if (opts.charter.status === 'dissolved') {
+        throw new Error('Cannot amend a dissolved charter');
+    }
+    // INV-5: No amendment during active dissolution grace period
+    if (opts.charter.status === 'suspended') {
+        throw new Error('Cannot amend a suspended charter');
+    }
+    const founderSig = {
+        publicKey: opts.proposerPublicKey,
+        role: 'proposer',
+        signedAt: now,
+        signature: sign(opts.charter.charterId + ':' + opts.description, opts.proposerPrivateKey),
+    };
+    return {
+        amendmentId: 'amend_' + uuidv4().slice(0, 12),
+        charterId: opts.charter.charterId,
+        fromVersion: opts.charter.version,
+        toVersion: opts.proposedCharter.version,
+        description: opts.description,
+        proposedCharter: opts.proposedCharter,
+        proposedBy: opts.proposerPublicKey,
+        proposedAt: now,
+        effectiveAt: opts.effectiveAt ?? now,
+        signatures: [founderSig],
+        status: 'proposed',
+    };
+}
+/** Add a signature to a charter amendment. */
+export function signAmendment(amendment, signerPrivateKey, signerPublicKey, signerRole) {
+    if (amendment.signatures.some(s => s.publicKey === signerPublicKey)) {
+        throw new Error(`Signer ${signerPublicKey.slice(0, 8)}... already signed this amendment`);
+    }
+    const sig = {
+        publicKey: signerPublicKey,
+        role: signerRole,
+        signedAt: new Date().toISOString(),
+        signature: sign(amendment.charterId + ':' + amendment.description, signerPrivateKey),
+    };
+    return { ...amendment, signatures: [...amendment.signatures, sig] };
+}
+// ══════════════════════════════════════
+// VERIFY AMENDMENT
+// ══════════════════════════════════════
+/** Verify a charter amendment against the charter's amendment policy. */
+export function verifyAmendment(amendment, charter) {
+    const errors = [];
+    // 1. Charter exists and matches
+    const charterExists = charter.charterId === amendment.charterId;
+    if (!charterExists)
+        errors.push('Amendment references unknown charter');
+    // 2. Version matches
+    const versionMatch = charter.version === amendment.fromVersion;
+    if (!versionMatch)
+        errors.push(`Version mismatch: charter is ${charter.version}, amendment targets ${amendment.fromVersion}`);
+    // 3. Verify individual signatures
+    let signaturesValid = true;
+    const sigContent = amendment.charterId + ':' + amendment.description;
+    for (const sig of amendment.signatures) {
+        try {
+            if (!verify(sigContent, sig.signature, sig.publicKey)) {
+                signaturesValid = false;
+                errors.push(`Invalid signature from ${sig.publicKey.slice(0, 8)}...`);
+            }
+        }
+        catch {
+            signaturesValid = false;
+            errors.push(`Signature verification failed for ${sig.publicKey.slice(0, 8)}...`);
+        }
+    }
+    // 4. Threshold met
+    const thresholdEval = evaluateThreshold(charter.amendmentPolicy, amendment.signatures.map(s => ({
+        publicKey: s.publicKey,
+        keyClass: s.role,
+        signedAt: s.signedAt,
+        signature: s.signature,
+    })));
+    const thresholdMet = thresholdEval.met;
+    if (!thresholdMet)
+        errors.push('Amendment does not meet charter amendment policy threshold');
+    // 5. Proposed charter is internally consistent
+    const proposedVerification = verifyCharter(amendment.proposedCharter);
+    const proposedCharterValid = proposedVerification.officesValid &&
+        proposedVerification.incompatibilityClean;
+    if (!proposedCharterValid) {
+        errors.push(...proposedVerification.errors.filter(e => e.includes('office') || e.includes('incompatible')));
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        charterExists,
+        versionMatch,
+        thresholdMet,
+        signaturesValid,
+        proposedCharterValid,
+    };
+}
+// ══════════════════════════════════════
+// OFFICE REGISTRY
+// ══════════════════════════════════════
+/** Create an OfficeRegistry from a charter's offices. */
+export function createOfficeRegistry(charter, successionRules, quorumFailurePolicies, signerPrivateKey) {
+    const registry = {
+        charterId: charter.charterId,
+        charterVersion: charter.version,
+        offices: charter.offices,
+        successionRules,
+        quorumFailurePolicies,
+        updatedAt: new Date().toISOString(),
+    };
+    const contentHash = charterHash(canonicalize(registry));
+    const signature = sign(canonicalize({ ...registry, contentHash }), signerPrivateKey);
+    return { ...registry, contentHash, signature };
+}
+/** Record an office holder change. */
+export function createOfficeTransfer(opts) {
+    const office = opts.charter.offices.find(o => o.officeId === opts.officeId);
+    if (!office)
+        throw new Error(`Office ${opts.officeId} not found in charter`);
+    const now = new Date().toISOString();
+    const transfer = {
+        transferId: 'transfer_' + uuidv4().slice(0, 12),
+        charterId: opts.charter.charterId,
+        officeId: opts.officeId,
+        fromHolder: opts.fromHolder,
+        toHolder: opts.toHolder,
+        trigger: opts.trigger,
+        transferredAt: now,
+        delegationHandling: opts.delegationHandling,
+        approvalSignatures: opts.approvalSignatures,
+    };
+    const signature = sign(canonicalize(transfer), opts.signerPrivateKey);
+    return { ...transfer, signature };
+}
+// ══════════════════════════════════════
+// APPROVAL REQUEST LIFECYCLE
+// ══════════════════════════════════════
+/** Create an approval request for a multi-party action. */
+export function createApprovalRequest(policyId, subject, subjectType, requestedBy, timeoutSeconds) {
+    const now = new Date().toISOString();
+    const expiresAt = new Date(Date.now() + timeoutSeconds * 1000).toISOString();
+    return {
+        requestId: 'approval_' + uuidv4().slice(0, 12),
+        policyId,
+        subject,
+        subjectType,
+        requestedBy,
+        requestedAt: now,
+        expiresAt,
+        signatures: [],
+        status: 'pending',
+    };
+}
+/** Add a signature to an approval request. Validates the signer
+ *  is not a duplicate and the request hasn't expired. */
+export function addApprovalSignature(request, signerPrivateKey, signerPublicKey, keyClass, officeId) {
+    if (request.status !== 'pending') {
+        throw new Error(`Cannot sign ${request.status} approval request`);
+    }
+    if (new Date(request.expiresAt) < new Date()) {
+        throw new Error('Approval request has expired');
+    }
+    if (request.signatures.some(s => s.publicKey === signerPublicKey)) {
+        throw new Error(`Signer ${signerPublicKey.slice(0, 8)}... already signed`);
+    }
+    const sigContent = request.requestId + ':' + request.subject;
+    const sig = {
+        publicKey: signerPublicKey,
+        keyClass,
+        officeId,
+        signedAt: new Date().toISOString(),
+        signature: sign(sigContent, signerPrivateKey),
+    };
+    return {
+        ...request,
+        signatures: [...request.signatures, sig],
+    };
+}
+/** Evaluate an approval request against its policy. For 'threshold'
+ *  type, delegates to evaluateThreshold. For simpler types, does
+ *  direct checks. Returns the updated request with status. */
+export function evaluateApprovalRequest(request, policy) {
+    const expired = new Date(request.expiresAt) < new Date();
+    if (policy.type === 'threshold' && policy.threshold) {
+        const evaluation = evaluateThreshold(policy.threshold, request.signatures);
+        evaluation.expired = expired;
+        const status = expired ? 'expired' :
+            evaluation.met ? 'approved' : 'pending';
+        return {
+            request: { ...request, status },
+            evaluation,
+        };
+    }
+    if (policy.type === 'role_required' && policy.requiredRoles) {
+        // Check that all required roles have at least one signature
+        const signedRoles = new Set(request.signatures
+            .filter(s => s.officeId)
+            .map(s => s.officeId));
+        const missingRoles = policy.requiredRoles.filter(r => !signedRoles.has(r));
+        const met = missingRoles.length === 0;
+        const evaluation = {
+            met: met && !expired,
+            classStatus: policy.requiredRoles.map(role => ({
+                role,
+                required: 1,
+                collected: signedRoles.has(role) ? 1 : 0,
+                satisfied: signedRoles.has(role),
+            })),
+            totalValidSignatures: request.signatures.length,
+            totalRequired: policy.requiredRoles.length,
+            expired,
+            errors: missingRoles.map(r => `Missing signature from office: ${r}`),
+        };
+        const status = expired ? 'expired' : met ? 'approved' : 'pending';
+        return { request: { ...request, status }, evaluation };
+    }
+    if (policy.type === 'sequential' && policy.sequentialOrder) {
+        // Check signatures arrived in the required order
+        const errors = [];
+        let met = true;
+        for (let i = 0; i < policy.sequentialOrder.length; i++) {
+            const requiredOffice = policy.sequentialOrder[i];
+            const sig = request.signatures[i];
+            if (!sig || sig.officeId !== requiredOffice) {
+                met = false;
+                errors.push(`Position ${i}: expected office ${requiredOffice}`);
+            }
+        }
+        const evaluation = {
+            met: met && !expired,
+            classStatus: policy.sequentialOrder.map((role, i) => ({
+                role,
+                required: 1,
+                collected: request.signatures[i]?.officeId === role ? 1 : 0,
+                satisfied: request.signatures[i]?.officeId === role,
+            })),
+            totalValidSignatures: request.signatures.length,
+            totalRequired: policy.sequentialOrder.length,
+            expired,
+            errors,
+        };
+        const status = expired ? 'expired' : met ? 'approved' : 'pending';
+        return { request: { ...request, status }, evaluation };
+    }
+    // Default / unanimous: all signatures present (fallback)
+    const evaluation = {
+        met: request.signatures.length > 0 && !expired,
+        classStatus: [],
+        totalValidSignatures: request.signatures.length,
+        totalRequired: 1,
+        expired,
+        errors: request.signatures.length === 0 ? ['No signatures collected'] : [],
+    };
+    const status = expired ? 'expired' :
+        request.signatures.length > 0 ? 'approved' : 'pending';
+    return { request: { ...request, status }, evaluation };
+}
+// ══════════════════════════════════════
+// OFFICE HELPERS
+// ══════════════════════════════════════
+/** Find an office by ID within a charter. */
+export function findOffice(charter, officeId) {
+    return charter.offices.find(o => o.officeId === officeId);
+}
+/** Find which office(s) a public key holds. */
+export function findOfficesByHolder(charter, publicKey) {
+    return charter.offices.filter(o => o.holderSet.some(h => h.publicKey === publicKey));
+}
+/** Resolve the successor office for a vacant office. Walks the
+ *  succession order and returns the first non-vacant office. */
+export function resolveSuccessor(charter, officeId) {
+    const office = findOffice(charter, officeId);
+    if (!office)
+        return null;
+    for (const succId of office.successionOrder) {
+        const succ = findOffice(charter, succId);
+        if (succ && succ.status === 'active' && succ.holderSet.length > 0) {
+            return succ;
+        }
+    }
+    return null;
+}
+/** Check if a holder can take an office without violating
+ *  incompatibility constraints (GPT #20). */
+export function checkIncompatibility(charter, officeId, holderPublicKey) {
+    const office = findOffice(charter, officeId);
+    if (!office)
+        return { compatible: false, conflicts: ['Office not found'] };
+    const conflicts = [];
+    const heldOffices = findOfficesByHolder(charter, holderPublicKey);
+    // Check if target office has incompatibility with currently held offices
+    if (office.incompatibleOffices) {
+        for (const held of heldOffices) {
+            if (office.incompatibleOffices.includes(held.officeId)) {
+                conflicts.push(`${officeId} is incompatible with ${held.officeId}`);
+            }
+        }
+    }
+    // Check reverse: do currently held offices declare this one incompatible?
+    for (const held of heldOffices) {
+        if (held.incompatibleOffices?.includes(officeId)) {
+            conflicts.push(`${held.officeId} is incompatible with ${officeId}`);
+        }
+    }
+    return { compatible: conflicts.length === 0, conflicts };
+}
+/** Check if an office has quorum per its QuorumFailurePolicy. */
+export function checkQuorum(office, policy) {
+    const holders = office.holderSet.length;
+    const required = policy?.minimumHolders ?? 1;
+    return {
+        hasQuorum: holders >= required,
+        holders,
+        required,
+    };
+}
+/** Check if a charter is in dissolution grace period. */
+export function isInDissolutionGrace(charter) {
+    return charter.status === 'dissolved';
+}
+/** Verify an office transfer signature. */
+export function verifyOfficeTransfer(transfer) {
+    const { signature, ...body } = transfer;
+    const canonical = canonicalize(body);
+    try {
+        // We don't know the signer — check against approval signatures
+        return transfer.approvalSignatures.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=charter.js.map