@axonflow/sdk 5.5.0 → 6.0.0

package/dist/esm/client.js

@@ -30,12 +30,12 @@ function mapIdempotencyKeyMismatch(err) {
  * Returns -1 if a < b, 0 if equal, 1 if a > b.
  */
 function compareSemver(a, b) {
-    const parseVersion = (v) => v.split('.').map(p => parseInt(p.split('-')[0], 10) || 0);
+    const parseVersion = (v) => v.split('.').map(p => parseInt(p.split('-')[0], 10) ?? 0);
     const aParts = parseVersion(a);
     const bParts = parseVersion(b);
     const len = Math.max(aParts.length, bParts.length);
     for (let i = 0; i < len; i++) {
-        const diff = (aParts[i] || 0) - (bParts[i] || 0);
+        const diff = (aParts[i] ?? 0) - (bParts[i] ?? 0);
         if (diff !== 0)
             return diff < 0 ? -1 : 1;
     }
@@ -64,7 +64,7 @@ export class AxonFlow {
             };
         }
         // Set defaults first to determine endpoint
-        const endpoint = config.endpoint || 'https://staging-eu.getaxonflow.com';
+        const endpoint = config.endpoint ?? 'https://staging-eu.getaxonflow.com';
         // Credentials check: OAuth2-style (clientId/clientSecret)
         const hasCredentials = !!(config.clientId && config.clientSecret);
         // Set configuration
@@ -72,19 +72,19 @@ export class AxonFlow {
             clientId: config.clientId,
             clientSecret: config.clientSecret,
             endpoint,
-            mode: config.mode || 'production',
-            tenant: config.tenant || '',
-            debug: config.debug || false,
-            timeout: config.timeout || 30000,
-            mapTimeout: config.mapTimeout || 120000, // 2 minutes for MAP operations
+            mode: config.mode ?? 'production',
+            tenant: config.tenant ?? '',
+            debug: config.debug ?? false,
+            timeout: config.timeout ?? 30000,
+            mapTimeout: config.mapTimeout ?? 120000, // 2 minutes for MAP operations
             retry: {
                 enabled: config.retry?.enabled !== false,
-                maxAttempts: config.retry?.maxAttempts || 3,
-                delay: config.retry?.delay || 1000,
+                maxAttempts: config.retry?.maxAttempts ?? 3,
+                delay: config.retry?.delay ?? 1000,
             },
             cache: {
                 enabled: config.cache?.enabled !== false,
-                ttl: config.cache?.ttl || 60000,
+                ttl: config.cache?.ttl ?? 60000,
             },
         };
         // Interceptors removed in v3.0.0 (deprecated wrapOpenAIClient/wrapAnthropicClient)
@@ -121,7 +121,7 @@ export class AxonFlow {
         // clientSecret defaults to empty string for community/no-secret mode.
         const effectiveClientId = this.getEffectiveClientId();
         if (effectiveClientId) {
-            const credentials = Buffer.from(`${effectiveClientId}:${this.config.clientSecret || ''}`).toString('base64');
+            const credentials = Buffer.from(`${effectiveClientId}:${this.config.clientSecret ?? ''}`).toString('base64');
             headers['Authorization'] = `Basic ${credentials}`;
         }
         // Include SDK version for version discovery and compatibility checks
@@ -138,6 +138,9 @@ export class AxonFlow {
      * @returns The clientId to use in requests
      */
     getEffectiveClientId() {
+        // Intentional || (not ??): an empty-string clientId/tenant is treated as
+        // "missing" by the SDK contract — see tests/smart-defaults.test.ts.
+        // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
         return this.config.clientId || this.config.tenant || 'community';
     }
     /**
@@ -209,7 +212,7 @@ export class AxonFlow {
             // If denied, throw error
             if (!governanceResponse.allowed) {
                 const violation = governanceResponse.violations?.[0];
-                throw new Error(`Request blocked by AxonFlow: ${violation?.description || 'Policy violation'}`);
+                throw new Error(`Request blocked by AxonFlow: ${violation?.description ?? 'Policy violation'}`);
             }
             // Execute the AI call (possibly with modifications)
             const modifiedCall = governanceResponse.modifiedRequest
@@ -259,6 +262,9 @@ export class AxonFlow {
         const agentRequest = {
             query: request.aiRequest.prompt,
             user_token: '',
+            // Intentional || (not ??): an empty-string clientId/tenant is treated as
+            // "missing" by the SDK contract — see tests/smart-defaults.test.ts.
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
             client_id: this.config.clientId || this.config.tenant,
             request_type: 'llm_chat',
             context: {
@@ -286,7 +292,7 @@ export class AxonFlow {
         const agentResponse = await response.json();
         // Transform Agent API response to SDK format
         // Extract policy name from policy_info if available
-        const policyName = agentResponse.policy_info?.policies_evaluated?.[0] || 'agent-policy';
+        const policyName = agentResponse.policy_info?.policies_evaluated?.[0] ?? 'agent-policy';
         return {
             requestId: request.requestId,
             allowed: !agentResponse.blocked,
@@ -295,17 +301,17 @@ export class AxonFlow {
                     {
                         type: 'security',
                         severity: 'high',
-                        description: agentResponse.block_reason || 'Request blocked by policy',
+                        description: agentResponse.block_reason ?? 'Request blocked by policy',
                         policy: policyName,
                         action: 'blocked',
                     },
                 ]
                 : [],
             modifiedRequest: agentResponse.data,
-            policies: agentResponse.policy_info?.policies_evaluated || [],
+            policies: agentResponse.policy_info?.policies_evaluated ?? [],
             audit: {
                 timestamp: Date.now(),
-                duration: parseInt(agentResponse.policy_info?.processing_time?.replace('ms', '') || '0'),
+                duration: parseInt(agentResponse.policy_info?.processing_time?.replace('ms', '') ?? '0'),
                 tenant: this.config.tenant,
             },
         };
@@ -319,7 +325,7 @@ export class AxonFlow {
         if (this.config.debug) {
             debugLog('Request processed', {
                 allowed: response.allowed,
-                violations: response.violations?.length || 0,
+                violations: response.violations?.length ?? 0,
                 duration: response.audit.duration,
             });
         }
@@ -328,9 +334,10 @@ export class AxonFlow {
      * Check if an error is from AxonFlow (vs the AI provider)
      */
     isAxonFlowError(error) {
-        return (error?.message?.includes('AxonFlow') ||
-            error?.message?.includes('governance') ||
-            error?.message?.includes('fetch'));
+        const msg = error?.message;
+        if (typeof msg !== 'string')
+            return false;
+        return msg.includes('AxonFlow') || msg.includes('governance') || msg.includes('fetch');
     }
     /**
      * Create a sandbox client for testing
@@ -526,13 +533,16 @@ export class AxonFlow {
      */
     async proxyLLMCall(options) {
         // Default to "anonymous" if userToken is empty/undefined (community mode)
-        const effectiveUserToken = options.userToken || 'anonymous';
+        const effectiveUserToken = options.userToken ?? 'anonymous';
         const agentRequest = {
             query: options.query,
             user_token: effectiveUserToken,
+            // Intentional || (not ??): an empty-string clientId/tenant is treated as
+            // "missing" by the SDK contract — see tests/smart-defaults.test.ts.
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
             client_id: this.config.clientId || this.config.tenant,
             request_type: options.requestType,
-            context: options.context || {},
+            context: options.context ?? {},
         };
         if (options.media && options.media.length > 0) {
             agentRequest.media = options.media.map(m => ({
@@ -585,7 +595,7 @@ export class AxonFlow {
                 try {
                     const errorJson = JSON.parse(errorText);
                     if (errorJson.blocked || errorJson.block_reason) {
-                        throw new PolicyViolationError(errorJson.block_reason || 'Request blocked by policy', errorJson.policy_info?.policies_evaluated);
+                        throw new PolicyViolationError(errorJson.block_reason ?? 'Request blocked by policy', errorJson.policy_info?.policies_evaluated);
                     }
                 }
                 catch (e) {
@@ -599,13 +609,11 @@ export class AxonFlow {
             }
         }
         // Parse response if not already parsed (from 402 handling)
-        if (!data) {
-            data = await response.json();
-        }
+        data ?? (data = await response.json());
         // Check for policy violation in successful response (some blocked responses return 200)
         // Note: Don't throw for budget blocks (402 responses) - return with budgetInfo instead
         if (data.blocked && !data.budget_info) {
-            throw new PolicyViolationError(data.block_reason || 'Request blocked by policy', data.policy_info?.policies_evaluated);
+            throw new PolicyViolationError(data.block_reason ?? 'Request blocked by policy', data.policy_info?.policies_evaluated);
         }
         // Transform snake_case response to camelCase
         const result = {
@@ -614,18 +622,18 @@ export class AxonFlow {
             result: data.result,
             planId: data.plan_id,
             requestId: data.request_id,
-            metadata: data.metadata || {},
+            metadata: data.metadata ?? {},
             error: data.error,
-            blocked: data.blocked || false,
+            blocked: data.blocked ?? false,
             blockReason: data.block_reason,
         };
         // Parse policy info if present
         if (data.policy_info) {
             result.policyInfo = {
-                policiesEvaluated: data.policy_info.policies_evaluated || [],
-                staticChecks: data.policy_info.static_checks || [],
-                processingTime: data.policy_info.processing_time || '',
-                tenantId: data.policy_info.tenant_id || '',
+                policiesEvaluated: data.policy_info.policies_evaluated ?? [],
+                staticChecks: data.policy_info.static_checks ?? [],
+                processingTime: data.policy_info.processing_time ?? '',
+                tenantId: data.policy_info.tenant_id ?? '',
                 codeArtifact: data.policy_info.code_artifact,
             };
         }
@@ -634,10 +642,10 @@ export class AxonFlow {
             result.budgetInfo = {
                 budgetId: data.budget_info.budget_id,
                 budgetName: data.budget_info.budget_name,
-                usedUsd: data.budget_info.used_usd || 0,
-                limitUsd: data.budget_info.limit_usd || 0,
-                percentage: data.budget_info.percentage || 0,
-                exceeded: data.budget_info.exceeded || false,
+                usedUsd: data.budget_info.used_usd ?? 0,
+                limitUsd: data.budget_info.limit_usd ?? 0,
+                percentage: data.budget_info.percentage ?? 0,
+                exceeded: data.budget_info.exceeded ?? false,
                 action: data.budget_info.action,
             };
         }
@@ -681,7 +689,7 @@ export class AxonFlow {
     async listConnectors() {
         const response = await this.orchestratorRequest('GET', '/api/v1/connectors');
         // Handle wrapped response
-        const connectors = Array.isArray(response) ? response : response.connectors || [];
+        const connectors = Array.isArray(response) ? response : (response.connectors ?? []);
         if (this.config.debug) {
             debugLog('Listed connectors', { count: connectors.length });
         }
@@ -734,11 +742,14 @@ export class AxonFlow {
         const agentRequest = {
             query,
             user_token: '',
+            // Intentional || (not ??): an empty-string clientId/tenant is treated as
+            // "missing" by the SDK contract — see tests/smart-defaults.test.ts.
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
             client_id: this.config.clientId || this.config.tenant,
             request_type: 'mcp-query',
             context: {
                 connector: connectorName,
-                params: params || {},
+                params: params ?? {},
             },
         };
         const url = `${this.config.endpoint}/api/request`;
@@ -807,7 +818,7 @@ export class AxonFlow {
         const body = {
             connector: options.connector,
             statement: options.statement,
-            options: options.options || {},
+            options: options.options ?? {},
         };
         if (this.config.debug) {
             debugLog('MCP Query', {
@@ -824,7 +835,7 @@ export class AxonFlow {
         const responseData = await response.json();
         // Handle policy blocks (403 responses)
         if (!response.ok) {
-            throw new ConnectorError(responseData.error || `MCP query failed: ${response.status} ${response.statusText}`, options.connector, 'mcpQuery');
+            throw new ConnectorError(responseData.error ?? `MCP query failed: ${response.status} ${response.statusText}`, options.connector, 'mcpQuery');
         }
         if (this.config.debug) {
             debugLog('MCP Query result', {
@@ -890,7 +901,7 @@ export class AxonFlow {
         if (options.parameters) {
             body.parameters = options.parameters;
         }
-        body.operation = options.operation || 'execute';
+        body.operation = options.operation ?? 'execute';
         if (this.config.debug) {
             debugLog('MCP Check Input', {
                 connectorType: options.connectorType,
@@ -906,7 +917,7 @@ export class AxonFlow {
         const responseData = await response.json();
         // 403 means policy blocked — this is a valid check response, not an error
         if (!response.ok && response.status !== 403) {
-            throw new ConnectorError(responseData.error || 'MCP check-input failed', options.connectorType, 'check-input');
+            throw new ConnectorError(responseData.error ?? 'MCP check-input failed', options.connectorType, 'check-input');
         }
         if (this.config.debug) {
             debugLog('MCP Check Input result', {
@@ -978,7 +989,7 @@ export class AxonFlow {
         const responseData = await response.json();
         // 403 means policy blocked — this is a valid check response, not an error
         if (!response.ok && response.status !== 403) {
-            throw new ConnectorError(responseData.error || 'MCP check-output failed', options.connectorType, 'check-output');
+            throw new ConnectorError(responseData.error ?? 'MCP check-output failed', options.connectorType, 'check-output');
         }
         if (this.config.debug) {
             debugLog('MCP Check Output result', {
@@ -1024,7 +1035,13 @@ export class AxonFlow {
         }
         const agentRequest = {
             query,
+            // Intentional || (not ??): an empty-string clientId/tenant is treated as
+            // "missing" by the SDK contract — see tests/smart-defaults.test.ts.
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
             user_token: userToken || this.config.clientId || this.config.tenant,
+            // Intentional || (not ??): an empty-string clientId/tenant is treated as
+            // "missing" by the SDK contract — see tests/smart-defaults.test.ts.
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
             client_id: this.config.clientId || this.config.tenant,
             request_type: 'multi-agent-plan',
             context,
@@ -1050,18 +1067,24 @@ export class AxonFlow {
             throw new PlanExecutionError(`Plan generation failed: ${agentResponse.error}`, undefined, 'generation');
         }
         // plan_id can be at top level or inside data
-        const planId = agentResponse.plan_id || agentResponse.data?.plan_id;
+        const planId = agentResponse.plan_id ?? agentResponse.data?.plan_id;
         if (this.config.debug) {
             debugLog('Plan generated', { planId });
         }
         return {
             planId,
-            status: agentResponse.data?.status || 'pending',
-            steps: agentResponse.data?.steps || [],
-            domain: agentResponse.data?.domain || domain || 'generic',
-            complexity: agentResponse.data?.complexity || 0,
-            parallel: agentResponse.data?.parallel || false,
-            metadata: agentResponse.metadata || {},
+            status: agentResponse.data?.status ?? 'pending',
+            steps: agentResponse.data?.steps ?? [],
+            domain: agentResponse.data?.domain ?? domain ?? 'generic',
+            complexity: agentResponse.data?.complexity ?? 0,
+            parallel: agentResponse.data?.parallel ?? false,
+            metadata: agentResponse.metadata ?? {},
+            success: agentResponse.success,
+            version: agentResponse.version ?? agentResponse.data?.version,
+            result: agentResponse.result ?? agentResponse.data?.result,
+            error: agentResponse.error,
+            workflow_execution_id: agentResponse.workflow_execution_id ?? agentResponse.data?.workflow_execution_id,
+            policy_info: agentResponse.policy_info ?? agentResponse.data?.policy_info,
         };
     }
     /**
@@ -1072,7 +1095,13 @@ export class AxonFlow {
     async executePlan(planId, userToken) {
         const agentRequest = {
             query: '',
+            // Intentional || (not ??): an empty-string clientId/tenant is treated as
+            // "missing" by the SDK contract — see tests/smart-defaults.test.ts.
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
             user_token: userToken || this.config.clientId || this.config.tenant,
+            // Intentional || (not ??): an empty-string clientId/tenant is treated as
+            // "missing" by the SDK contract — see tests/smart-defaults.test.ts.
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
             client_id: this.config.clientId || this.config.tenant,
             request_type: 'execute-plan',
             context: { plan_id: planId },
@@ -1104,7 +1133,7 @@ export class AxonFlow {
             if (data.error && !error)
                 error = data.error;
             // Throw on nested failure (e.g., cancelled plan execution)
-            throw new PlanExecutionError(error || 'Plan execution failed', planId, 'execution');
+            throw new PlanExecutionError(error ?? 'Plan execution failed', planId, 'execution');
         }
         if (!result && data?.result)
             result = data.result;
@@ -1186,8 +1215,13 @@ export class AxonFlow {
             debugLog('Plan cancelled', { planId, status: data.status });
         }
         return {
-            planId: data.plan_id || planId,
+            planId: data.plan_id ?? planId,
             status: data.status,
+            // `success` is the canonical wire boolean. The deprecated
+            // `message` slot is also kept populated for back-compat
+            // readers; on a current server it will always be undefined
+            // because the wire never emits it.
+            success: data.success,
             message: data.message,
         };
     }
@@ -1212,6 +1246,9 @@ export class AxonFlow {
         if (request.domain) {
             body.domain = request.domain;
         }
+        if (request.metadata !== undefined) {
+            body.metadata = request.metadata;
+        }
         const response = await fetch(url, {
             method: 'PUT',
             headers,
@@ -1231,7 +1268,7 @@ export class AxonFlow {
             debugLog('Plan updated', { planId, version: data.version });
         }
         return {
-            planId: data.plan_id || planId,
+            planId: data.plan_id ?? planId,
             version: data.version,
             status: data.status,
             success: data.success ?? true,
@@ -1256,7 +1293,7 @@ export class AxonFlow {
             throw new PlanExecutionError(`Get plan versions failed: ${response.status} ${response.statusText} - ${errorText}`, planId, 'versions');
         }
         const data = await response.json();
-        const versions = (data.versions || []).map((v) => ({
+        const versions = (data.versions ?? []).map((v) => ({
             version: v.version,
             changedAt: v.changed_at,
             changedBy: v.changed_by,
@@ -1264,7 +1301,7 @@ export class AxonFlow {
             changeSummary: v.change_summary,
         }));
         return {
-            planId: data.plan_id || planId,
+            planId: data.plan_id ?? planId,
             versions,
         };
     }
@@ -1294,9 +1331,13 @@ export class AxonFlow {
             debugLog('Plan resumed', { planId, approved: data.approved });
         }
         return {
-            planId: data.plan_id || planId,
+            planId: data.plan_id ?? planId,
             status: data.status,
+            // `result` is the canonical wire-aggregated outcome on resume.
+            result: data.result,
             approved: data.approved,
+            // `message` kept populated for the back-compat alias; legacy
+            // path read this slot historically.
             message: data.message,
         };
     }
@@ -1359,8 +1400,8 @@ export class AxonFlow {
             user_token: options.userToken,
             client_id: clientId,
             query: options.query,
-            data_sources: options.dataSources || [],
-            context: options.context || {},
+            data_sources: options.dataSources ?? [],
+            context: options.context ?? {},
         };
         const headers = {
             'Content-Type': 'application/json',
@@ -1391,9 +1432,9 @@ export class AxonFlow {
         const result = {
             contextId: data.context_id,
             approved: data.approved,
-            requiresRedaction: data.requires_redaction || false,
-            approvedData: data.approved_data || {},
-            policies: data.policies || [],
+            requiresRedaction: data.requires_redaction ?? false,
+            approvedData: data.approved_data ?? {},
+            policies: data.policies ?? [],
             expiresAt,
             blockReason: data.block_reason,
         };
@@ -1452,7 +1493,7 @@ export class AxonFlow {
                 total_tokens: options.tokenUsage.totalTokens,
             },
             latency_ms: options.latencyMs,
-            metadata: options.metadata || {},
+            metadata: options.metadata ?? {},
         };
         const headers = {
             'Content-Type': 'application/json',
@@ -1571,7 +1612,7 @@ export class AxonFlow {
         const response = await this.orchestratorRequest('GET', '/api/v1/circuit-breaker/status');
         const data = response.data;
         return {
-            activeCircuits: (data.active_circuits || []).map(c => ({
+            activeCircuits: (data.active_circuits ?? []).map(c => ({
                 id: c.id,
                 scope: c.scope,
                 scopeId: c.scope_id,
@@ -1614,7 +1655,7 @@ export class AxonFlow {
         const response = await this.orchestratorRequest('GET', path);
         const data = response.data;
         return {
-            history: (data.history || []).map(h => ({
+            history: (data.history ?? []).map(h => ({
                 id: h.id,
                 orgId: h.org_id,
                 scope: h.scope,
@@ -1870,10 +1911,10 @@ export class AxonFlow {
      * forward compatibility per ADR-043.
      */
     parseDecisionExplanation(raw) {
-        const r = raw || {};
-        const rawMatches = r.policy_matches || [];
+        const r = raw ?? {};
+        const rawMatches = r.policy_matches ?? [];
         const policyMatches = rawMatches.map(m => ({
-            policyId: m.policy_id || '',
+            policyId: m.policy_id ?? '',
             policyName: m.policy_name,
             action: m.action,
             riskLevel: m.risk_level,
@@ -1882,18 +1923,18 @@ export class AxonFlow {
         }));
         const rawRules = r.matched_rules;
         const matchedRules = rawRules?.map(m => ({
-            policyId: m.policy_id || '',
+            policyId: m.policy_id ?? '',
             ruleId: m.rule_id,
             ruleText: m.rule_text,
             matchedOn: m.matched_on,
         }));
         return {
-            decisionId: r.decision_id || '',
+            decisionId: r.decision_id ?? '',
             timestamp: r.timestamp ? new Date(r.timestamp) : new Date(),
             policyMatches,
             matchedRules,
-            decision: r.decision || '',
-            reason: r.reason || '',
+            decision: r.decision ?? '',
+            reason: r.reason ?? '',
             riskLevel: r.risk_level,
             overrideAvailable: r.override_available ?? false,
             overrideExistingId: r.override_existing_id,
@@ -1940,7 +1981,7 @@ export class AxonFlow {
             };
         }
         const data = response;
-        const entries = (data.entries || []).map(e => this.parseAuditLogEntry(e));
+        const entries = (data.entries ?? []).map(e => this.parseAuditLogEntry(e));
         return {
             entries,
             total: data.total ?? entries.length,
@@ -1994,7 +2035,7 @@ export class AxonFlow {
             };
         }
         const data = response;
-        const entries = (data.entries || []).map(e => this.parseAuditLogEntry(e));
+        const entries = (data.entries ?? []).map(e => this.parseAuditLogEntry(e));
         return {
             entries,
             total: data.total ?? entries.length,
@@ -2114,7 +2155,7 @@ export class AxonFlow {
         }
         // Backend returns { policies: [], pagination: {} }, extract the array
         const response = await this.policyRequest('GET', path);
-        return response.policies || [];
+        return response.policies ?? [];
     }
     /**
      * Get a specific static policy by ID.
@@ -2165,12 +2206,19 @@ export class AxonFlow {
             severity: policy.severity,
             enabled: policy.enabled,
             action: policy.action,
-            tier: policy.tier || 'tenant',
+            tier: policy.tier ?? 'tenant',
         };
         // Add organization_id for organization tier policies
         if (policy.organizationId) {
             requestBody.organization_id = policy.organizationId;
         }
+        // Wire-canonical fields surfaced in the v6 alignment sweep.
+        if (policy.priority !== undefined) {
+            requestBody.priority = policy.priority;
+        }
+        if (policy.tags !== undefined) {
+            requestBody.tags = policy.tags;
+        }
         return this.policyRequest('POST', '/api/v1/static-policies', requestBody);
     }
     /**
@@ -2259,7 +2307,7 @@ export class AxonFlow {
         }
         // Backend returns { static: [], dynamic: [], ... }, extract the static array
         const response = await this.policyRequest('GET', path);
-        return response.static || [];
+        return response.static ?? [];
     }
     /**
      * Test a regex pattern against sample inputs.
@@ -2304,12 +2352,21 @@ export class AxonFlow {
             debugLog('Getting static policy versions', { id });
         }
         const response = await this.policyRequest('GET', `/api/v1/static-policies/${id}/versions`);
-        // Transform snake_case API response to camelCase
+        // Transform snake_case API response to camelCase, populating
+        // both the wire-canonical fields (`id`, `policy_id`,
+        // `change_summary`, `snapshot`) and the legacy aliases (kept for
+        // back-compat; will read undefined on a current server).
         return response.versions.map(v => ({
+            id: v.id,
+            policy_id: v.policy_id,
             version: v.version,
             changedBy: v.changed_by,
             changedAt: v.changed_at,
             changeType: v.change_type,
+            change_summary: v.change_summary,
+            snapshot: v.snapshot,
+            // @deprecated aliases — only populated if a legacy server
+            // still emits them; current servers don't.
             changeDescription: v.change_description,
             previousValues: v.previous_values,
             newValues: v.new_values,
@@ -2378,7 +2435,7 @@ export class AxonFlow {
             debugLog('Listing policy overrides');
         }
         const response = await this.policyRequest('GET', '/api/v1/static-policies/overrides');
-        return response.overrides || [];
+        return response.overrides ?? [];
     }
     // ============================================================================
     // Dynamic Policy Methods
@@ -2425,7 +2482,7 @@ export class AxonFlow {
         // API returns {"policies": [...]} wrapper via Agent proxy
         const response = await this.orchestratorRequest('GET', path);
         // Handle both wrapped and unwrapped responses for compatibility
-        return Array.isArray(response) ? response : response.policies || [];
+        return Array.isArray(response) ? response : (response.policies ?? []);
     }
     /**
      * Get a specific dynamic policy by ID.
@@ -2480,7 +2537,7 @@ export class AxonFlow {
             requestBody.priority = policy.priority;
         if (policy.enabled !== undefined)
             requestBody.enabled = policy.enabled;
-        requestBody.tier = policy.tier || 'tenant';
+        requestBody.tier = policy.tier ?? 'tenant';
         if (policy.organizationId) {
             requestBody.organization_id = policy.organizationId;
         }
@@ -2574,7 +2631,7 @@ export class AxonFlow {
         // API returns {"policies": [...]} wrapper via Agent proxy
         const response = await this.orchestratorRequest('GET', path);
         // Handle both wrapped and unwrapped responses for compatibility
-        return Array.isArray(response) ? response : response.policies || [];
+        return Array.isArray(response) ? response : (response.policies ?? []);
     }
     // ============================================================================
     // Portal Authentication Methods (Enterprise)
@@ -2903,7 +2960,7 @@ export class AxonFlow {
         const response = await this.portalRequest('GET', path);
         // Transform snake_case response to camelCase
         return {
-            prs: (response.prs || []).map(pr => ({
+            prs: (response.prs ?? []).map(pr => ({
                 id: pr.id,
                 prNumber: pr.pr_number,
                 prUrl: pr.pr_url,
@@ -3109,7 +3166,7 @@ export class AxonFlow {
         }
         const response = await this.portalRequest('GET', path);
         return {
-            records: (response.records || []).map(r => ({
+            records: (response.records ?? []).map(r => ({
                 id: r.id,
                 prNumber: r.pr_number,
                 prUrl: r.pr_url,
@@ -3285,7 +3342,7 @@ export class AxonFlow {
         }
         const response = await this.orchestratorRequest('GET', path);
         return {
-            executions: (response.executions || []).map(e => ({
+            executions: (response.executions ?? []).map(e => ({
                 requestId: e.request_id,
                 workflowName: e.workflow_name,
                 status: e.status,
@@ -3369,6 +3426,7 @@ export class AxonFlow {
                 approvalRequired: s.approval_required,
                 approvedBy: s.approved_by,
                 approvedAt: s.approved_at,
+                retryCount: s.retry_count,
             })),
         };
     }
@@ -3412,6 +3470,7 @@ export class AxonFlow {
             approvalRequired: s.approval_required,
             approvedBy: s.approved_by,
             approvedAt: s.approved_at,
+            retryCount: s.retry_count,
         }));
     }
     /**
@@ -3550,8 +3609,8 @@ export class AxonFlow {
         const path = `/api/v1/budgets${queryString ? `?${queryString}` : ''}`;
         const response = await this.orchestratorRequest('GET', path);
         return {
-            budgets: (response.budgets || []).map(b => this.mapBudgetResponse(b)),
-            total: response.total || 0,
+            budgets: (response.budgets ?? []).map(b => this.mapBudgetResponse(b)),
+            total: response.total ?? 0,
         };
     }
     /**
@@ -3595,13 +3654,13 @@ export class AxonFlow {
         const response = await this.orchestratorRequest('GET', `/api/v1/budgets/${budgetId}/status`);
         return {
             budget: this.mapBudgetResponse(response.budget),
-            usedUsd: response.used_usd || 0,
-            remainingUsd: response.remaining_usd || 0,
-            percentage: response.percentage || 0,
-            isExceeded: response.is_exceeded || false,
-            isBlocked: response.is_blocked || false,
-            periodStart: response.period_start || '',
-            periodEnd: response.period_end || '',
+            usedUsd: response.used_usd ?? 0,
+            remainingUsd: response.remaining_usd ?? 0,
+            percentage: response.percentage ?? 0,
+            isExceeded: response.is_exceeded ?? false,
+            isBlocked: response.is_blocked ?? false,
+            periodStart: response.period_start ?? '',
+            periodEnd: response.period_end ?? '',
         };
     }
     /**
@@ -3612,19 +3671,20 @@ export class AxonFlow {
      */
     async getBudgetAlerts(budgetId) {
         const response = await this.orchestratorRequest('GET', `/api/v1/budgets/${budgetId}/alerts`);
-        const alerts = (response.alerts || []).map((a) => ({
-            id: a.id || '',
-            budgetId: a.budget_id || '',
-            alertType: a.alert_type || '',
-            threshold: a.threshold || 0,
-            percentageReached: a.percentage_reached || 0,
-            amountUsd: a.amount_usd || 0,
-            message: a.message || '',
-            createdAt: a.created_at || '',
+        const alerts = (response.alerts ?? []).map((a) => ({
+            id: a.id ?? '',
+            budgetId: a.budget_id ?? '',
+            alertType: a.alert_type ?? '',
+            threshold: a.threshold ?? 0,
+            percentageReached: a.percentage_reached ?? 0,
+            amountUsd: a.amount_usd ?? 0,
+            message: a.message ?? '',
+            createdAt: a.created_at ?? '',
+            acknowledged: a.acknowledged,
         }));
         return {
             alerts,
-            count: response.count || 0,
+            count: response.count ?? 0,
         };
     }
     /**
@@ -3647,11 +3707,11 @@ export class AxonFlow {
             body.user_id = request.userId;
         const response = await this.orchestratorRequest('POST', '/api/v1/budgets/check', body);
         return {
-            allowed: response.allowed || false,
+            allowed: response.allowed ?? false,
             action: response.action,
             message: response.message,
             budgets: response.budgets
-                ? (response.budgets || []).map(b => this.mapBudgetResponse(b))
+                ? (response.budgets ?? []).map(b => this.mapBudgetResponse(b))
                 : undefined,
         };
     }
@@ -3668,14 +3728,14 @@ export class AxonFlow {
         const path = period ? `/api/v1/usage?period=${period}` : '/api/v1/usage';
         const response = await this.orchestratorRequest('GET', path);
         return {
-            totalCostUsd: response.total_cost_usd || 0,
-            totalRequests: response.total_requests || 0,
-            totalTokensIn: response.total_tokens_in || 0,
-            totalTokensOut: response.total_tokens_out || 0,
-            averageCostPerRequest: response.average_cost_per_request || 0,
-            period: response.period || '',
-            periodStart: response.period_start || '',
-            periodEnd: response.period_end || '',
+            totalCostUsd: response.total_cost_usd ?? 0,
+            totalRequests: response.total_requests ?? 0,
+            totalTokensIn: response.total_tokens_in ?? 0,
+            totalTokensOut: response.total_tokens_out ?? 0,
+            averageCostPerRequest: response.average_cost_per_request ?? 0,
+            period: response.period ?? '',
+            periodStart: response.period_start ?? '',
+            periodEnd: response.period_end ?? '',
         };
     }
     /**
@@ -3691,21 +3751,22 @@ export class AxonFlow {
         if (period)
             params.set('period', period);
         const response = await this.orchestratorRequest('GET', `/api/v1/usage/breakdown?${params.toString()}`);
-        const items = (response.items || []).map((i) => ({
-            groupValue: i.group_value || '',
-            costUsd: i.cost_usd || 0,
-            percentage: i.percentage || 0,
-            requestCount: i.request_count || 0,
-            tokensIn: i.tokens_in || 0,
-            tokensOut: i.tokens_out || 0,
+        const items = (response.items ?? []).map((i) => ({
+            groupBy: i.group_by,
+            groupValue: i.group_value ?? '',
+            costUsd: i.cost_usd ?? 0,
+            percentage: i.percentage ?? 0,
+            requestCount: i.request_count ?? 0,
+            tokensIn: i.tokens_in ?? 0,
+            tokensOut: i.tokens_out ?? 0,
         }));
         return {
-            groupBy: response.group_by || '',
-            totalCostUsd: response.total_cost_usd || 0,
+            groupBy: response.group_by ?? '',
+            totalCostUsd: response.total_cost_usd ?? 0,
             items,
-            period: response.period || '',
-            periodStart: response.period_start || '',
-            periodEnd: response.period_end || '',
+            period: response.period ?? '',
+            periodStart: response.period_start ?? '',
+            periodEnd: response.period_end ?? '',
         };
     }
     /**
@@ -3727,21 +3788,33 @@ export class AxonFlow {
         const queryString = params.toString();
         const path = `/api/v1/usage/records${queryString ? `?${queryString}` : ''}`;
         const response = await this.orchestratorRequest('GET', path);
-        const records = (response.records || []).map((r) => ({
-            id: r.id || '',
-            provider: r.provider || '',
-            model: r.model || '',
-            tokensIn: r.tokens_in || 0,
-            tokensOut: r.tokens_out || 0,
-            costUsd: r.cost_usd || 0,
+        const records = (response.records ?? []).map((r) => ({
+            id: r.id ?? '',
+            provider: r.provider ?? '',
+            model: r.model ?? '',
+            tokensIn: r.tokens_in ?? 0,
+            tokensOut: r.tokens_out ?? 0,
+            costUsd: r.cost_usd ?? 0,
             requestId: r.request_id,
             orgId: r.org_id,
             agentId: r.agent_id,
+            // Wire-canonical fields surfaced in the v6 alignment sweep.
+            // The `timestamp` legacy field below has always read undefined
+            // because the server emits `created_at`; both kept populated
+            // so existing readers of `timestamp` see no behavior change.
+            created_at: r.created_at,
+            success: r.success,
+            error_message: r.error_message,
+            latency_ms: r.latency_ms,
+            team_id: r.team_id,
+            tenant_id: r.tenant_id,
+            user_id: r.user_id,
+            workflow_id: r.workflow_id,
             timestamp: r.timestamp,
         }));
         return {
             records,
-            total: response.total || 0,
+            total: response.total ?? 0,
         };
     }
     // ========================================
@@ -3769,7 +3842,7 @@ export class AxonFlow {
             const pricing = this.mapPricingResponse(response);
             return { pricing: [pricing] };
         }
-        const pricingList = (response.pricing || []).map(p => this.mapPricingResponse(p));
+        const pricingList = (response.pricing ?? []).map(p => this.mapPricingResponse(p));
         return { pricing: pricingList };
     }
     // ========================================
@@ -3777,15 +3850,17 @@ export class AxonFlow {
     // ========================================
     mapBudgetResponse(response) {
         return {
-            id: response.id || '',
-            name: response.name || '',
-            scope: response.scope || '',
-            limitUsd: response.limit_usd || 0,
-            period: response.period || '',
-            onExceed: response.on_exceed || '',
-            alertThresholds: response.alert_thresholds || [],
+            id: response.id ?? '',
+            name: response.name ?? '',
+            scope: response.scope ?? '',
+            limitUsd: response.limit_usd ?? 0,
+            period: response.period ?? '',
+            onExceed: response.on_exceed ?? '',
+            alertThresholds: response.alert_thresholds ?? [],
             enabled: response.enabled ?? true,
             scopeId: response.scope_id,
+            tenant_id: response.tenant_id,
+            org_id: response.org_id,
             createdAt: response.created_at,
             updatedAt: response.updated_at,
         };
@@ -3793,11 +3868,11 @@ export class AxonFlow {
     mapPricingResponse(response) {
         const pricingData = response.pricing;
         return {
-            provider: response.provider || '',
-            model: response.model || '',
+            provider: response.provider ?? '',
+            model: response.model ?? '',
             pricing: {
-                inputPer1k: pricingData?.input_per_1k || 0,
-                outputPer1k: pricingData?.output_per_1k || 0,
+                inputPer1k: pricingData?.input_per_1k ?? 0,
+                outputPer1k: pricingData?.output_per_1k ?? 0,
             },
         };
     }
@@ -3994,7 +4069,7 @@ export class AxonFlow {
             throw new ConfigurationError('Step ID is required');
         }
         try {
-            await this.orchestratorRequest('POST', `/api/v1/workflows/${workflowId}/steps/${stepId}/complete`, request || {});
+            await this.orchestratorRequest('POST', `/api/v1/workflows/${workflowId}/steps/${stepId}/complete`, request ?? {});
         }
         catch (err) {
             const idem = mapIdempotencyKeyMismatch(err);
@@ -4113,26 +4188,37 @@ export class AxonFlow {
     /**
      * Approve a workflow step that requires human approval.
      *
-     * Call this to approve a step that was gated with a 'require_approval' decision.
+     * The server requires `comment` with a minimum of 10 characters — it's the
+     * audit-trail justification that every approval carries into the workflow
+     * history. Callers should always supply a meaningful comment.
      *
      * @param workflowId - ID of the workflow
      * @param stepId - ID of the step to approve
+     * @param comment - Audit justification for the approval (min 10 chars)
      * @returns Approval response with status
      *
      * @example
      * ```typescript
-     * const result = await client.approveStep('wf_123', 'step_456');
+     * const result = await client.approveStep(
+     *   'wf_123',
+     *   'step_456',
+     *   'Approved after full audit review'
+     * );
      * console.log(`Step ${result.step_id} status: ${result.status}`);
      * ```
      */
-    async approveStep(workflowId, stepId) {
+    async approveStep(workflowId, stepId, comment) {
         if (!workflowId) {
             throw new ConfigurationError('Workflow ID is required');
         }
         if (!stepId) {
             throw new ConfigurationError('Step ID is required');
         }
-        return this.orchestratorRequest('POST', `/api/v1/workflow-control/${workflowId}/steps/${stepId}/approve`, {});
+        const body = {};
+        if (comment) {
+            body.comment = comment;
+        }
+        return this.orchestratorRequest('POST', `/api/v1/workflows/${workflowId}/steps/${stepId}/approve`, body);
     }
     /**
      * Reject a workflow step that requires human approval.
@@ -4161,21 +4247,26 @@ export class AxonFlow {
         if (reason) {
             body.reason = reason;
         }
-        return this.orchestratorRequest('POST', `/api/v1/workflow-control/${workflowId}/steps/${stepId}/reject`, body);
+        return this.orchestratorRequest('POST', `/api/v1/workflows/${workflowId}/steps/${stepId}/reject`, body);
     }
     /**
-     * Get pending approvals for workflow steps.
+     * Get pending approvals for workflow steps — the WCP-plane listing.
+     *
+     * Lists steps that are waiting for human approval across all planes for
+     * the caller's tenant. Use {@link getPendingPlanApprovals} for the
+     * MAP-plane listing (scopes to MAP-backed workflows and populates
+     * `plan_id` on every entry).
      *
-     * Lists all steps that are waiting for human approval across all workflows.
+     * Available on Evaluation+ licenses.
      *
      * @param options - Optional filtering options
-     * @returns List of pending approvals with total count
+     * @returns List of pending approvals with count
      *
      * @example
      * ```typescript
      * const pending = await client.getPendingApprovals({ limit: 10 });
-     * console.log(`${pending.total} approvals pending`);
-     * for (const approval of pending.approvals) {
+     * console.log(`${pending.count} approvals pending`);
+     * for (const approval of pending.pending_approvals) {
      *   console.log(`${approval.workflow_name} / ${approval.step_name}`);
      * }
      * ```
@@ -4187,8 +4278,44 @@ export class AxonFlow {
         }
         const queryString = params.toString();
         const path = queryString
-            ? `/api/v1/workflow-control/pending-approvals?${queryString}`
-            : '/api/v1/workflow-control/pending-approvals';
+            ? `/api/v1/workflows/approvals/pending?${queryString}`
+            : '/api/v1/workflows/approvals/pending';
+        return this.orchestratorRequest('GET', path);
+    }
+    /**
+     * List pending approvals for MAP-backed workflows — the MAP-plane
+     * counterpart of {@link getPendingApprovals}. Every entry has `plan_id`
+     * populated. Pass `options.plan_id` to scope the listing to a single plan.
+     *
+     * Requires an Evaluation or Enterprise license (same tier gate as the
+     * MAP step approve/reject endpoints).
+     *
+     * @param options - Optional filtering options (`limit`, `plan_id`)
+     * @returns List of MAP-plane pending approvals with count
+     *
+     * @example
+     * ```typescript
+     * const pending = await client.getPendingPlanApprovals({
+     *   plan_id: 'plan-abc123',
+     *   limit: 10,
+     * });
+     * for (const approval of pending.pending_approvals) {
+     *   console.log(`Plan ${approval.plan_id} step ${approval.step_id} awaiting approval`);
+     * }
+     * ```
+     */
+    async getPendingPlanApprovals(options) {
+        const params = new URLSearchParams();
+        if (options?.limit !== undefined) {
+            params.set('limit', options.limit.toString());
+        }
+        if (options?.plan_id) {
+            params.set('plan_id', options.plan_id);
+        }
+        const queryString = params.toString();
+        const path = queryString
+            ? `/api/v1/plans/approvals/pending?${queryString}`
+            : '/api/v1/plans/approvals/pending';
         return this.orchestratorRequest('GET', path);
     }
     // =============================================================================
@@ -4228,7 +4355,7 @@ export class AxonFlow {
             debugLog('Plan rolled back', { planId, version: data.version });
         }
         return {
-            planId: data.plan_id || planId,
+            planId: data.plan_id ?? planId,
             version: data.version,
             previousVersion: data.previous_version,
             status: data.status,
@@ -4494,7 +4621,7 @@ export class AxonFlow {
             throw new APIError(response.status, response.statusText, errorText);
         }
         const data = await response.json();
-        return (data || []).map((s) => this.mapSystemResponse(s));
+        return (data ?? []).map((s) => this.mapSystemResponse(s));
     }
     async masfeatActivateSystem(systemId) {
         // Use PUT to update status - the /activate endpoint doesn't exist
@@ -4549,8 +4676,8 @@ export class AxonFlow {
             highMaterialityCount: data.high_materiality_count ?? data.high_materiality ?? 0,
             mediumMaterialityCount: data.medium_materiality_count ?? data.medium_materiality ?? 0,
             lowMaterialityCount: data.low_materiality_count ?? data.low_materiality ?? 0,
-            byUseCase: data.by_use_case || {},
-            byStatus: data.by_status || {},
+            byUseCase: data.by_use_case ?? {},
+            byStatus: data.by_status ?? {},
         };
     }
     // Assessment Methods
@@ -4558,7 +4685,7 @@ export class AxonFlow {
         const url = `${this.config.endpoint}/api/v1/masfeat/assessments`;
         const body = {
             system_id: request.systemId,
-            assessment_type: request.assessmentType || 'periodic',
+            assessment_type: request.assessmentType ?? 'periodic',
             assessors: request.assessors,
         };
         if (request.assessmentDate)
@@ -4697,7 +4824,7 @@ export class AxonFlow {
             throw new APIError(response.status, response.statusText, errorText);
         }
         const data = await response.json();
-        return (data || []).map((a) => this.mapAssessmentResponse(a));
+        return (data ?? []).map((a) => this.mapAssessmentResponse(a));
     }
     async masfeatSubmitAssessment(assessmentId) {
         const url = `${this.config.endpoint}/api/v1/masfeat/assessments/${assessmentId}/submit`;
@@ -4913,20 +5040,20 @@ export class AxonFlow {
         if (data && typeof data === 'object' && 'history' in data) {
             data = data.history;
         }
-        return (data || []).map((e) => ({
+        return (data ?? []).map((e) => ({
             id: e.id,
             killSwitchId: e.kill_switch_id,
             // Handle both API formats: event_type (SDK expected) vs action (API actual)
-            eventType: e.event_type || e.action,
+            eventType: e.event_type ?? e.action,
             // Build eventData from additional fields if not present
-            eventData: e.event_data ||
-                (e.previous_status || e.new_status || e.reason
+            eventData: e.event_data ??
+                ((e.previous_status ?? e.new_status ?? e.reason)
                     ? { previousStatus: e.previous_status, newStatus: e.new_status, reason: e.reason }
                     : undefined),
             // Handle both API formats: created_by vs performed_by
-            createdBy: e.created_by || e.performed_by,
+            createdBy: e.created_by ?? e.performed_by,
             // Handle both API formats: created_at vs performed_at
-            createdAt: new Date(e.created_at || e.performed_at),
+            createdAt: new Date(e.created_at ?? e.performed_at),
         }));
     }
     // Helper methods for MAS FEAT
@@ -4940,7 +5067,7 @@ export class AxonFlow {
             useCase: data.use_case,
             ownerTeam: data.owner_team,
             technicalOwner: data.technical_owner,
-            businessOwner: data.business_owner || data.owner_email,
+            businessOwner: data.business_owner ?? data.owner_email,
             customerImpact: data.customer_impact ?? data.risk_rating_impact,
             modelComplexity: data.model_complexity ?? data.risk_rating_complexity,
             humanReliance: data.human_reliance ?? data.risk_rating_reliance,
@@ -4961,6 +5088,7 @@ export class AxonFlow {
             description: data.description,
             status: data.status,
             remediation: data.remediation,
+            article: data.article,
             dueDate: data.due_date ? new Date(data.due_date) : undefined,
         };
     }
@@ -5008,7 +5136,7 @@ export class AxonFlow {
             autoTriggerEnabled: data.auto_trigger_enabled,
             triggeredAt: data.triggered_at ? new Date(data.triggered_at) : undefined,
             triggeredBy: data.triggered_by,
-            triggeredReason: data.triggered_reason || data.trigger_reason,
+            triggeredReason: data.triggered_reason ?? data.trigger_reason,
             restoredAt: data.restored_at ? new Date(data.restored_at) : undefined,
             restoredBy: data.restored_by,
             createdAt: new Date(data.created_at),
@@ -5181,7 +5309,7 @@ export class AxonFlow {
         }
         const response = await this.orchestratorRequest('GET', path);
         return {
-            items: response.data || [],
+            items: response.data ?? [],
             total: response.meta?.total ?? 0,
             has_more: (response.meta?.offset ?? 0) + (response.data?.length ?? 0) < (response.meta?.total ?? 0),
         };
@@ -5486,7 +5614,7 @@ export class AxonFlow {
                 // Process complete SSE events (separated by double newline)
                 const events = buffer.split('\n\n');
                 // Keep the last (potentially incomplete) chunk in the buffer
-                buffer = events.pop() || '';
+                buffer = events.pop() ?? '';
                 for (const event of events) {
                     const trimmed = event.trim();
                     if (!trimmed) {