@private.me/xbind 3.0.0 → 3.0.2

package/dist-standalone/cjs/version-info.js

@@ -1 +1,543 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.Capability=void 0,exports.getVersion=getVersion,exports.hasCapability=hasCapability,exports.getCapabilities=getCapabilities,exports.getDeprecationInfo=getDeprecationInfo,exports.warnIfDeprecated=warnIfDeprecated,exports.parseVersion=parseVersion,exports.compareVersions=compareVersions,exports.checkCompatibility=checkCompatibility,exports.getMinimumVersionFor=getMinimumVersionFor,exports.assertMinimumVersion=assertMinimumVersion;const logger_js_1=require("./logger.js"),logger=(0,logger_js_1.createLogger)("version-info");var Capability;!function(e){e.ENVELOPE_V1="envelope-v1",e.ENVELOPE_V2="envelope-v2",e.ENVELOPE_V3="envelope-v3",e.ENVELOPE_V4="envelope-v4",e.ML_KEM_768="ml-kem-768",e.ML_DSA_65="ml-dsa-65",e.X25519_ECDH="x25519-ecdh",e.ED25519_SIG="ed25519-sig",e.XORIDA="xorida",e.SPLIT_CHANNEL="split-channel",e.TRUST_REGISTRY="trust-registry",e.SERVICE_DISCOVERY="service-discovery",e.INVITE_SYSTEM="invite-system",e.AGENT_CALL="agent-call",e.XFETCH="xfetch",e.DUAL_MODE="dual-mode",e.BACKUP_RESTORE="backup-restore",e.CORRELATION_ID="correlation-id",e.STRUCTURED_LOGGING="structured-logging",e.DID_SUCCESSION="did-succession",e.GATEWAY_STATE="gateway-state",e.SUBSCRIPTION_PROOF="subscription-proof",e.POLICY_ENGINE="policy-engine",e.APPROVAL_FLOW="approval-flow",e.GUARDRAILS="guardrails",e.HTTP_COMPAT="http-compat",e.DID_WEB="did-web",e.DID_PRIVATEME="did:privateme",e.REDIS_NONCE="redis-nonce",e.RETRY_TRANSPORT="retry-transport"}(Capability||(exports.Capability=Capability={}));const VERSION_METADATA={semver:"3.0.0",major:1,minor:4,patch:2,prerelease:void 0,build:void 0,features:[Capability.ENVELOPE_V1,Capability.ENVELOPE_V2,Capability.ENVELOPE_V3,Capability.ENVELOPE_V4,Capability.ML_KEM_768,Capability.ML_DSA_65,Capability.X25519_ECDH,Capability.ED25519_SIG,Capability.XORIDA,Capability.SPLIT_CHANNEL,Capability.TRUST_REGISTRY,Capability.SERVICE_DISCOVERY,Capability.INVITE_SYSTEM,Capability.AGENT_CALL,Capability.XFETCH,Capability.DUAL_MODE,Capability.BACKUP_RESTORE,Capability.CORRELATION_ID,Capability.STRUCTURED_LOGGING,Capability.DID_SUCCESSION,Capability.GATEWAY_STATE,Capability.SUBSCRIPTION_PROOF,Capability.POLICY_ENGINE,Capability.APPROVAL_FLOW,Capability.GUARDRAILS,Capability.HTTP_COMPAT,Capability.DID_WEB,Capability.DID_PRIVATEME,Capability.REDIS_NONCE,Capability.RETRY_TRANSPORT],deprecated:[{name:"envelope-v1",since:"1.2.0",removedIn:"2.0.0",migration:"Use createEnvelopeV2() or higher for split-channel support",docs:"https://private.me/docs/xbind/migration-v2"}],buildDate:(new Date).toISOString(),nodeVersion:process.version};function getVersion(){return Object.freeze({...VERSION_METADATA})}function hasCapability(e){return VERSION_METADATA.features.includes(e)}function getCapabilities(){return Object.freeze([...VERSION_METADATA.features])}function getDeprecationInfo(e){return VERSION_METADATA.deprecated.find(i=>i.name===e)}const warnedFeatures=new Set;function warnIfDeprecated(e){if(warnedFeatures.has(e))return;const i=getDeprecationInfo(e);if(!i)return;warnedFeatures.add(e);const r=[`Feature "${e}" is deprecated since v${i.since}`,i.removedIn?`and will be removed in v${i.removedIn}.`:".",i.migration].join(" ");logger.warn(r,{feature:e,deprecatedSince:i.since,removedIn:i.removedIn,docs:i.docs}),"undefined"!=typeof console&&console.warn&&(console.warn(`[xBind] ${r}`),i.docs&&console.warn(`[xBind] See: ${i.docs}`))}function parseVersion(e){const i=e.match(/^(\d+)\.(\d+)\.(\d+)(?:-([a-zA-Z0-9.-]+))?(?:\+([a-zA-Z0-9.-]+))?$/);if(!(i&&i[1]&&i[2]&&i[3]))throw new Error(`Invalid semantic version: ${e}`);return{major:parseInt(i[1],10),minor:parseInt(i[2],10),patch:parseInt(i[3],10),prerelease:i[4]||void 0,build:i[5]||void 0}}function compareVersions(e,i){const r=parseVersion(e),a=parseVersion(i);if(r.major<a.major)return-1;if(r.major>a.major)return 1;if(r.minor<a.minor)return-1;if(r.minor>a.minor)return 1;if(r.patch<a.patch)return-1;if(r.patch>a.patch)return 1;if(r.prerelease&&!a.prerelease)return-1;if(!r.prerelease&&a.prerelease)return 1;if(r.prerelease&&a.prerelease){if(r.prerelease<a.prerelease)return-1;if(r.prerelease>a.prerelease)return 1}return 0}function checkCompatibility(e){const i=VERSION_METADATA.semver;if(e.startsWith("^")){const r=e.slice(1),a=parseVersion(r);return parseVersion(i).major!==a.major?{compatible:!1,message:`Incompatible major version. Required: ^${r}, Current: ${i}`,severity:"error",required:e,actual:i}:compareVersions(i,r)<0?{compatible:!1,message:`SDK version too old. Required: ^${r}, Current: ${i}`,severity:"error",required:e,actual:i}:{compatible:!0,message:`Compatible (${i} satisfies ^${r})`,severity:"info",required:e,actual:i}}if(e.startsWith("~")){const r=e.slice(1),a=parseVersion(r),t=parseVersion(i);return t.major!==a.major||t.minor!==a.minor?{compatible:!1,message:`Incompatible version. Required: ~${r}, Current: ${i}`,severity:"error",required:e,actual:i}:compareVersions(i,r)<0?{compatible:!1,message:`SDK version too old. Required: ~${r}, Current: ${i}`,severity:"error",required:e,actual:i}:{compatible:!0,message:`Compatible (${i} satisfies ~${r})`,severity:"info",required:e,actual:i}}let r,a,t;try{r=compareVersions(i,e)}catch(r){return{compatible:!1,message:`Invalid version format: ${e}`,severity:"error",required:e,actual:i}}if(0===r)return{compatible:!0,message:`Exact version match (${i})`,severity:"info",required:e,actual:i};if(r<0)return{compatible:!1,message:`SDK version too old. Required: ${e}, Current: ${i}`,severity:"error",required:e,actual:i};try{a=parseVersion(e),t=parseVersion(i)}catch(r){return{compatible:!0,message:`Compatible (${i} is newer than ${e})`,severity:"info",required:e,actual:i}}return t.major>a.major?{compatible:!1,message:`Breaking changes in SDK. Required: ${e}, Current: ${i}`,severity:"warning",required:e,actual:i}:{compatible:!0,message:`Compatible (${i} is newer than ${e})`,severity:"info",required:e,actual:i}}function getMinimumVersionFor(e){return{[Capability.ENVELOPE_V1]:"1.0.0",[Capability.ENVELOPE_V2]:"1.1.0",[Capability.ENVELOPE_V3]:"1.2.0",[Capability.ENVELOPE_V4]:"1.3.0",[Capability.ML_KEM_768]:"1.2.0",[Capability.ML_DSA_65]:"1.3.0",[Capability.X25519_ECDH]:"1.0.0",[Capability.ED25519_SIG]:"1.0.0",[Capability.XORIDA]:"1.0.0",[Capability.SPLIT_CHANNEL]:"1.1.0",[Capability.TRUST_REGISTRY]:"1.0.0",[Capability.SERVICE_DISCOVERY]:"1.1.0",[Capability.INVITE_SYSTEM]:"1.1.0",[Capability.AGENT_CALL]:"1.0.0",[Capability.XFETCH]:"1.2.0",[Capability.DUAL_MODE]:"1.2.0",[Capability.BACKUP_RESTORE]:"1.3.0",[Capability.CORRELATION_ID]:"1.3.0",[Capability.STRUCTURED_LOGGING]:"1.3.0",[Capability.DID_SUCCESSION]:"1.2.0",[Capability.GATEWAY_STATE]:"1.2.0",[Capability.SUBSCRIPTION_PROOF]:"1.2.0",[Capability.POLICY_ENGINE]:"1.1.0",[Capability.APPROVAL_FLOW]:"1.1.0",[Capability.GUARDRAILS]:"1.2.0",[Capability.HTTP_COMPAT]:"1.2.0",[Capability.DID_WEB]:"1.1.0",[Capability.DID_PRIVATEME]:"1.2.0",[Capability.REDIS_NONCE]:"1.1.0",[Capability.RETRY_TRANSPORT]:"1.1.0"}[e]}function assertMinimumVersion(e,i){const r=checkCompatibility(e);if(!r.compatible&&"error"===r.severity){const a=i?`${i} requires xBind >= ${e} (current: ${VERSION_METADATA.semver})`:r.message;throw new Error(a)}}
+"use strict";
+/**
+ * @module version-info
+ * Runtime SDK version information and capability detection
+ *
+ * Provides version metadata, feature flags, deprecation warnings,
+ * and compatibility checks for the xBind SDK.
+ *
+ * Usage:
+ * ```typescript
+ * import { getVersion, hasCapability, checkCompatibility } from '@private.me/xbind';
+ *
+ * // Get version information
+ * const version = getVersion();
+ * console.log(version.semver); // "1.4.0"
+ * console.log(version.features); // ["envelope-v4", "ml-kem-768", ...]
+ *
+ * // Check capabilities
+ * if (hasCapability('envelope-v4')) {
+ *   // Use v4 envelopes
+ * }
+ *
+ * // Compatibility check
+ * const compat = checkCompatibility('1.0.0');
+ * if (!compat.compatible) {
+ *   console.warn(compat.message);
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Capability = void 0;
+exports.getVersion = getVersion;
+exports.hasCapability = hasCapability;
+exports.getCapabilities = getCapabilities;
+exports.getDeprecationInfo = getDeprecationInfo;
+exports.warnIfDeprecated = warnIfDeprecated;
+exports.parseVersion = parseVersion;
+exports.compareVersions = compareVersions;
+exports.checkCompatibility = checkCompatibility;
+exports.getMinimumVersionFor = getMinimumVersionFor;
+exports.assertMinimumVersion = assertMinimumVersion;
+const logger_js_1 = require("./logger.js");
+const logger = (0, logger_js_1.createLogger)('version-info');
+/**
+ * Feature capability flags
+ */
+var Capability;
+(function (Capability) {
+    /** Transport Envelope v1 support */
+    Capability["ENVELOPE_V1"] = "envelope-v1";
+    /** Transport Envelope v2 support (split-channel) */
+    Capability["ENVELOPE_V2"] = "envelope-v2";
+    /** Transport Envelope v3 support (hybrid PQ) */
+    Capability["ENVELOPE_V3"] = "envelope-v3";
+    /** Transport Envelope v4 support (ML-DSA signatures) */
+    Capability["ENVELOPE_V4"] = "envelope-v4";
+    /** ML-KEM-768 post-quantum KEM */
+    Capability["ML_KEM_768"] = "ml-kem-768";
+    /** ML-DSA-65 post-quantum signatures */
+    Capability["ML_DSA_65"] = "ml-dsa-65";
+    /** X25519 ECDH key agreement */
+    Capability["X25519_ECDH"] = "x25519-ecdh";
+    /** Ed25519 signatures */
+    Capability["ED25519_SIG"] = "ed25519-sig";
+    /** XorIDA threshold sharing */
+    Capability["XORIDA"] = "xorida";
+    /** Split-channel transport */
+    Capability["SPLIT_CHANNEL"] = "split-channel";
+    /** Trust registry support */
+    Capability["TRUST_REGISTRY"] = "trust-registry";
+    /** Service discovery (mDNS) */
+    Capability["SERVICE_DISCOVERY"] = "service-discovery";
+    /** Invite system (viral growth) */
+    Capability["INVITE_SYSTEM"] = "invite-system";
+    /** Agent.call() API */
+    Capability["AGENT_CALL"] = "agent-call";
+    /** xFetch auto-upgrade */
+    Capability["XFETCH"] = "xfetch";
+    /** Dual-mode adapter (xBind + API key fallback) */
+    Capability["DUAL_MODE"] = "dual-mode";
+    /** Encrypted backup/restore */
+    Capability["BACKUP_RESTORE"] = "backup-restore";
+    /** Correlation ID tracing */
+    Capability["CORRELATION_ID"] = "correlation-id";
+    /** Structured logging */
+    Capability["STRUCTURED_LOGGING"] = "structured-logging";
+    /** DID succession */
+    Capability["DID_SUCCESSION"] = "did-succession";
+    /** Gateway connection state */
+    Capability["GATEWAY_STATE"] = "gateway-state";
+    /** Subscription proofs (portability) */
+    Capability["SUBSCRIPTION_PROOF"] = "subscription-proof";
+    /** Policy engine (constraints) */
+    Capability["POLICY_ENGINE"] = "policy-engine";
+    /** Approval flow (consent) */
+    Capability["APPROVAL_FLOW"] = "approval-flow";
+    /** Guardrails (error suggestions) */
+    Capability["GUARDRAILS"] = "guardrails";
+    /** HTTP client compatibility (axios, got) */
+    Capability["HTTP_COMPAT"] = "http-compat";
+    /** did:web resolver */
+    Capability["DID_WEB"] = "did-web";
+    /** did:privateme method */
+    Capability["DID_PRIVATEME"] = "did:privateme";
+    /** Redis nonce store */
+    Capability["REDIS_NONCE"] = "redis-nonce";
+    /** Retry transport */
+    Capability["RETRY_TRANSPORT"] = "retry-transport";
+})(Capability || (exports.Capability = Capability = {}));
+/**
+ * Current version metadata (extracted at build time)
+ */
+const VERSION_METADATA = {
+    semver: '3.0.0',
+    major: 1,
+    minor: 4,
+    patch: 2,
+    prerelease: undefined,
+    build: undefined,
+    features: [
+        Capability.ENVELOPE_V1,
+        Capability.ENVELOPE_V2,
+        Capability.ENVELOPE_V3,
+        Capability.ENVELOPE_V4,
+        Capability.ML_KEM_768,
+        Capability.ML_DSA_65,
+        Capability.X25519_ECDH,
+        Capability.ED25519_SIG,
+        Capability.XORIDA,
+        Capability.SPLIT_CHANNEL,
+        Capability.TRUST_REGISTRY,
+        Capability.SERVICE_DISCOVERY,
+        Capability.INVITE_SYSTEM,
+        Capability.AGENT_CALL,
+        Capability.XFETCH,
+        Capability.DUAL_MODE,
+        Capability.BACKUP_RESTORE,
+        Capability.CORRELATION_ID,
+        Capability.STRUCTURED_LOGGING,
+        Capability.DID_SUCCESSION,
+        Capability.GATEWAY_STATE,
+        Capability.SUBSCRIPTION_PROOF,
+        Capability.POLICY_ENGINE,
+        Capability.APPROVAL_FLOW,
+        Capability.GUARDRAILS,
+        Capability.HTTP_COMPAT,
+        Capability.DID_WEB,
+        Capability.DID_PRIVATEME,
+        Capability.REDIS_NONCE,
+        Capability.RETRY_TRANSPORT,
+    ],
+    deprecated: [
+        {
+            name: 'envelope-v1',
+            since: '1.2.0',
+            removedIn: '2.0.0',
+            migration: 'Use createEnvelopeV2() or higher for split-channel support',
+            docs: 'https://private.me/docs/xbind/migration-v2',
+        },
+    ],
+    buildDate: new Date().toISOString(),
+    nodeVersion: process.version,
+};
+/**
+ * Get SDK version information
+ *
+ * Returns complete version metadata including semver, capabilities,
+ * deprecated features, and build information.
+ *
+ * @returns Version information object
+ *
+ * @example
+ * ```typescript
+ * const version = getVersion();
+ * console.log(`xBind v${version.semver}`);
+ * console.log(`Features: ${version.features.join(', ')}`);
+ * ```
+ */
+function getVersion() {
+    return Object.freeze({ ...VERSION_METADATA });
+}
+/**
+ * Check if SDK supports a specific capability
+ *
+ * @param capability - Capability name to check
+ * @returns True if capability is supported
+ *
+ * @example
+ * ```typescript
+ * if (hasCapability('envelope-v4')) {
+ *   // Use ML-DSA signatures
+ * }
+ * ```
+ */
+function hasCapability(capability) {
+    return VERSION_METADATA.features.includes(capability);
+}
+/**
+ * Get all supported capabilities
+ *
+ * @returns Array of capability names
+ */
+function getCapabilities() {
+    return Object.freeze([...VERSION_METADATA.features]);
+}
+/**
+ * Check if a feature is deprecated
+ *
+ * @param feature - Feature name to check
+ * @returns Deprecation info if deprecated, undefined otherwise
+ */
+function getDeprecationInfo(feature) {
+    return VERSION_METADATA.deprecated.find((d) => d.name === feature);
+}
+/**
+ * Emit deprecation warning if feature is deprecated
+ *
+ * Logs warning message with migration instructions if the feature
+ * is marked as deprecated. Safe to call multiple times (warnings
+ * are deduplicated).
+ *
+ * @param feature - Feature name to check
+ *
+ * @example
+ * ```typescript
+ * warnIfDeprecated('envelope-v1');
+ * // Logs: "Warning: envelope-v1 is deprecated since 1.2.0..."
+ * ```
+ */
+const warnedFeatures = new Set();
+function warnIfDeprecated(feature) {
+    if (warnedFeatures.has(feature)) {
+        return; // Already warned
+    }
+    const info = getDeprecationInfo(feature);
+    if (!info) {
+        return; // Not deprecated
+    }
+    warnedFeatures.add(feature);
+    const message = [
+        `Feature "${feature}" is deprecated since v${info.since}`,
+        info.removedIn ? `and will be removed in v${info.removedIn}.` : '.',
+        info.migration,
+    ].join(' ');
+    logger.warn(message, {
+        feature,
+        deprecatedSince: info.since,
+        removedIn: info.removedIn,
+        docs: info.docs,
+    });
+    // Also log to console for visibility
+    // eslint-disable-next-line no-console
+    if (typeof console !== 'undefined' && console.warn) {
+        // eslint-disable-next-line no-console
+        console.warn(`[xBind] ${message}`);
+        if (info.docs) {
+            // eslint-disable-next-line no-console
+            console.warn(`[xBind] See: ${info.docs}`);
+        }
+    }
+}
+/**
+ * Parse semantic version string
+ *
+ * @param version - Version string (e.g., "1.3.5-beta.1+abc123")
+ * @returns Parsed version components
+ */
+function parseVersion(version) {
+    // Match semver pattern: MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-([a-zA-Z0-9.-]+))?(?:\+([a-zA-Z0-9.-]+))?$/);
+    if (!match || !match[1] || !match[2] || !match[3]) {
+        throw new Error(`Invalid semantic version: ${version}`);
+    }
+    return {
+        major: parseInt(match[1], 10),
+        minor: parseInt(match[2], 10),
+        patch: parseInt(match[3], 10),
+        prerelease: match[4] || undefined,
+        build: match[5] || undefined,
+    };
+}
+/**
+ * Compare two semantic versions
+ *
+ * @param a - First version
+ * @param b - Second version
+ * @returns -1 if a < b, 0 if a == b, 1 if a > b
+ */
+function compareVersions(a, b) {
+    const parsedA = parseVersion(a);
+    const parsedB = parseVersion(b);
+    // Compare major
+    if (parsedA.major < parsedB.major)
+        return -1;
+    if (parsedA.major > parsedB.major)
+        return 1;
+    // Compare minor
+    if (parsedA.minor < parsedB.minor)
+        return -1;
+    if (parsedA.minor > parsedB.minor)
+        return 1;
+    // Compare patch
+    if (parsedA.patch < parsedB.patch)
+        return -1;
+    if (parsedA.patch > parsedB.patch)
+        return 1;
+    // Compare prerelease (semver: 1.0.0-alpha < 1.0.0)
+    if (parsedA.prerelease && !parsedB.prerelease)
+        return -1;
+    if (!parsedA.prerelease && parsedB.prerelease)
+        return 1;
+    if (parsedA.prerelease && parsedB.prerelease) {
+        if (parsedA.prerelease < parsedB.prerelease)
+            return -1;
+        if (parsedA.prerelease > parsedB.prerelease)
+            return 1;
+    }
+    return 0;
+}
+/**
+ * Check version compatibility
+ *
+ * Determines if the current SDK version is compatible with a
+ * required version constraint. Follows semantic versioning rules:
+ * - Breaking changes increment major version
+ * - Minor/patch updates are backward compatible
+ *
+ * @param requiredVersion - Required version or range (e.g., "1.0.0", "^1.2.0")
+ * @returns Compatibility result with message
+ *
+ * @example
+ * ```typescript
+ * const compat = checkCompatibility('1.0.0');
+ * if (!compat.compatible) {
+ *   throw new Error(compat.message);
+ * }
+ * ```
+ */
+function checkCompatibility(requiredVersion) {
+    const current = VERSION_METADATA.semver;
+    // Handle caret range (^1.2.0 means >=1.2.0 <2.0.0)
+    if (requiredVersion.startsWith('^')) {
+        const minVersion = requiredVersion.slice(1);
+        const minParsed = parseVersion(minVersion);
+        const currentParsed = parseVersion(current);
+        // Major must match
+        if (currentParsed.major !== minParsed.major) {
+            return {
+                compatible: false,
+                message: `Incompatible major version. Required: ^${minVersion}, Current: ${current}`,
+                severity: 'error',
+                required: requiredVersion,
+                actual: current,
+            };
+        }
+        // Current must be >= min version
+        if (compareVersions(current, minVersion) < 0) {
+            return {
+                compatible: false,
+                message: `SDK version too old. Required: ^${minVersion}, Current: ${current}`,
+                severity: 'error',
+                required: requiredVersion,
+                actual: current,
+            };
+        }
+        return {
+            compatible: true,
+            message: `Compatible (${current} satisfies ^${minVersion})`,
+            severity: 'info',
+            required: requiredVersion,
+            actual: current,
+        };
+    }
+    // Handle tilde range (~1.2.0 means >=1.2.0 <1.3.0)
+    if (requiredVersion.startsWith('~')) {
+        const minVersion = requiredVersion.slice(1);
+        const minParsed = parseVersion(minVersion);
+        const currentParsed = parseVersion(current);
+        // Major and minor must match
+        if (currentParsed.major !== minParsed.major ||
+            currentParsed.minor !== minParsed.minor) {
+            return {
+                compatible: false,
+                message: `Incompatible version. Required: ~${minVersion}, Current: ${current}`,
+                severity: 'error',
+                required: requiredVersion,
+                actual: current,
+            };
+        }
+        // Current must be >= min version
+        if (compareVersions(current, minVersion) < 0) {
+            return {
+                compatible: false,
+                message: `SDK version too old. Required: ~${minVersion}, Current: ${current}`,
+                severity: 'error',
+                required: requiredVersion,
+                actual: current,
+            };
+        }
+        return {
+            compatible: true,
+            message: `Compatible (${current} satisfies ~${minVersion})`,
+            severity: 'info',
+            required: requiredVersion,
+            actual: current,
+        };
+    }
+    // Exact version match or comparison
+    let cmp;
+    try {
+        cmp = compareVersions(current, requiredVersion);
+    }
+    catch (error) {
+        // Invalid version format
+        return {
+            compatible: false,
+            message: `Invalid version format: ${requiredVersion}`,
+            severity: 'error',
+            required: requiredVersion,
+            actual: current,
+        };
+    }
+    if (cmp === 0) {
+        return {
+            compatible: true,
+            message: `Exact version match (${current})`,
+            severity: 'info',
+            required: requiredVersion,
+            actual: current,
+        };
+    }
+    if (cmp < 0) {
+        return {
+            compatible: false,
+            message: `SDK version too old. Required: ${requiredVersion}, Current: ${current}`,
+            severity: 'error',
+            required: requiredVersion,
+            actual: current,
+        };
+    }
+    // Current version is newer - check major version compatibility
+    let requiredParsed;
+    let currentParsed;
+    try {
+        requiredParsed = parseVersion(requiredVersion);
+        currentParsed = parseVersion(current);
+    }
+    catch (error) {
+        // Version parsing error, already newer
+        return {
+            compatible: true,
+            message: `Compatible (${current} is newer than ${requiredVersion})`,
+            severity: 'info',
+            required: requiredVersion,
+            actual: current,
+        };
+    }
+    if (currentParsed.major > requiredParsed.major) {
+        return {
+            compatible: false,
+            message: `Breaking changes in SDK. Required: ${requiredVersion}, Current: ${current}`,
+            severity: 'warning',
+            required: requiredVersion,
+            actual: current,
+        };
+    }
+    return {
+        compatible: true,
+        message: `Compatible (${current} is newer than ${requiredVersion})`,
+        severity: 'info',
+        required: requiredVersion,
+        actual: current,
+    };
+}
+/**
+ * Get recommended SDK version for a feature
+ *
+ * Returns the minimum SDK version required to use a specific feature.
+ *
+ * @param feature - Feature or capability name
+ * @returns Minimum version string, or undefined if feature is unknown
+ */
+function getMinimumVersionFor(feature) {
+    // Feature introduction versions
+    const featureVersions = {
+        [Capability.ENVELOPE_V1]: '1.0.0',
+        [Capability.ENVELOPE_V2]: '1.1.0',
+        [Capability.ENVELOPE_V3]: '1.2.0',
+        [Capability.ENVELOPE_V4]: '1.3.0',
+        [Capability.ML_KEM_768]: '1.2.0',
+        [Capability.ML_DSA_65]: '1.3.0',
+        [Capability.X25519_ECDH]: '1.0.0',
+        [Capability.ED25519_SIG]: '1.0.0',
+        [Capability.XORIDA]: '1.0.0',
+        [Capability.SPLIT_CHANNEL]: '1.1.0',
+        [Capability.TRUST_REGISTRY]: '1.0.0',
+        [Capability.SERVICE_DISCOVERY]: '1.1.0',
+        [Capability.INVITE_SYSTEM]: '1.1.0',
+        [Capability.AGENT_CALL]: '1.0.0',
+        [Capability.XFETCH]: '1.2.0',
+        [Capability.DUAL_MODE]: '1.2.0',
+        [Capability.BACKUP_RESTORE]: '1.3.0',
+        [Capability.CORRELATION_ID]: '1.3.0',
+        [Capability.STRUCTURED_LOGGING]: '1.3.0',
+        [Capability.DID_SUCCESSION]: '1.2.0',
+        [Capability.GATEWAY_STATE]: '1.2.0',
+        [Capability.SUBSCRIPTION_PROOF]: '1.2.0',
+        [Capability.POLICY_ENGINE]: '1.1.0',
+        [Capability.APPROVAL_FLOW]: '1.1.0',
+        [Capability.GUARDRAILS]: '1.2.0',
+        [Capability.HTTP_COMPAT]: '1.2.0',
+        [Capability.DID_WEB]: '1.1.0',
+        [Capability.DID_PRIVATEME]: '1.2.0',
+        [Capability.REDIS_NONCE]: '1.1.0',
+        [Capability.RETRY_TRANSPORT]: '1.1.0',
+    };
+    return featureVersions[feature];
+}
+/**
+ * Assert minimum SDK version
+ *
+ * Throws an error if the current SDK version does not meet the
+ * minimum required version.
+ *
+ * @param minVersion - Minimum required version
+ * @param context - Optional context message
+ * @throws Error if version is too old
+ *
+ * @example
+ * ```typescript
+ * assertMinimumVersion('1.2.0', 'ML-KEM-768 support');
+ * // Throws if SDK < 1.2.0
+ * ```
+ */
+function assertMinimumVersion(minVersion, context) {
+    const compat = checkCompatibility(minVersion);
+    if (!compat.compatible && compat.severity === 'error') {
+        const message = context
+            ? `${context} requires xBind >= ${minVersion} (current: ${VERSION_METADATA.semver})`
+            : compat.message;
+        throw new Error(message);
+    }
+}