xytara 2.3.0 → 2.4.0

package/lib/commerce_authority.js

@@ -0,0 +1,449 @@
+"use strict";
+
+function normalizeString(value, fallback = null) {
+  const trimmed = typeof value === "string" ? value.trim() : "";
+  return trimmed || fallback;
+}
+
+function ensureArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function listMapValuesByAccount(map, accountId) {
+  return Array.from(map.values()).filter((item) => item && item.account_id === accountId);
+}
+
+function listExternalCreditGrantsForAccount(state, accountId) {
+  return Array.from(state.externalCreditGrants.values()).filter((item) => item && item.account_id === accountId);
+}
+
+function listSpendCredentialsForAccount(state, accountId) {
+  return Array.from(state.accountSpendCredentials.values()).filter((item) => item && item.account_id === accountId);
+}
+
+function listAuthorityBindingsForAccount(state, accountId) {
+  return Array.from(state.accountAuthorityBindings.values()).filter((item) => item && item.account_id === accountId);
+}
+
+function listDelegatedTransactionsForCredential(state, credentialId) {
+  return Array.from(state.transactions.values())
+    .map((entry) => entry && entry.transaction)
+    .filter((transaction) =>
+      transaction &&
+      transaction.payment &&
+      transaction.payment.verification_mode === "delegated_spend_credential" &&
+      transaction.payment.wallet_id === credentialId
+    );
+}
+
+function buildAuthoritySummary(state, accountId) {
+  const bindings = listAuthorityBindingsForAccount(state, accountId);
+  const credentials = listSpendCredentialsForAccount(state, accountId);
+  const grants = listExternalCreditGrantsForAccount(state, accountId);
+  const entitlements = listMapValuesByAccount(state.economicsEntitlements, accountId);
+  const agents = listMapValuesByAccount(state.economicsAgents, accountId);
+  const budgets = listMapValuesByAccount(state.economicsBudgets, accountId);
+
+  const activeCredentials = credentials.filter((entry) => entry.status === "active");
+  const activeBindings = bindings.filter((entry) => entry.status === "active");
+  const revokedCredentials = credentials.filter((entry) => entry.status === "revoked");
+  const boundedCredentials = activeCredentials.filter((entry) => entry.spend_posture === "bounded_spend");
+  const openCredentials = activeCredentials.filter((entry) => entry.spend_posture === "open_spend");
+  const entitlementBoundCredentials = activeCredentials.filter((entry) => entry.entitlement_id);
+  const packBoundCredentials = activeCredentials.filter((entry) => !entry.entitlement_id && entry.pack_id);
+  const activeEntitlements = entitlements.filter((entry) => entry.status === "active" && Number(entry.remaining_units || 0) > 0);
+  const activeAgents = agents.filter((entry) => entry.status === "active");
+  const activeBudgets = budgets.filter((entry) => entry.status === "active");
+
+  let delegatedSpendState = "no_delegated_spend";
+  if (activeBindings.length > 0 || activeCredentials.length > 0) {
+    delegatedSpendState = boundedCredentials.length > 0 ? "bounded_delegated_spend_available" : "open_delegated_spend_available";
+  }
+
+  let authorityState = "unbound";
+  if (activeEntitlements.length > 0 || grants.length > 0) authorityState = "funded";
+  if (activeAgents.length > 0 || activeBudgets.length > 0 || activeBindings.length > 0 || activeCredentials.length > 0) authorityState = "governed";
+
+  return {
+    summary_version: "xytara-authority-summary-v1",
+    account_id: accountId,
+    authority_state: authorityState,
+    delegated_spend_state: delegatedSpendState,
+    entitlement_binding_state: entitlementBoundCredentials.length > 0
+      ? "entitlement_bound_delegation_present"
+      : packBoundCredentials.length > 0
+        ? "pack_bound_delegation_present"
+        : activeEntitlements.length > 0
+          ? "funded_without_bound_delegation"
+          : "no_entitlement_binding",
+    bounded_policy_state: activeAgents.length > 0 || activeBudgets.length > 0
+      ? "bounded_policy_present"
+      : "no_bounded_policy",
+    external_funding_state: grants.length > 0 ? "external_funding_present" : "no_external_funding_recorded",
+    counts: {
+      spend_credential_count: credentials.length,
+      authority_binding_count: bindings.length,
+      active_authority_binding_count: activeBindings.length,
+      active_spend_credential_count: activeCredentials.length,
+      revoked_spend_credential_count: revokedCredentials.length,
+      bounded_spend_credential_count: boundedCredentials.length,
+      open_spend_credential_count: openCredentials.length,
+      external_credit_grant_count: grants.length,
+      entitlement_count: entitlements.length,
+      active_entitlement_count: activeEntitlements.length,
+      economics_agent_count: agents.length,
+      active_economics_agent_count: activeAgents.length,
+      economics_budget_count: budgets.length,
+      active_economics_budget_count: activeBudgets.length
+    },
+    authority_units: {
+      granted_units: grants.reduce((sum, entry) => sum + Number(entry.units || 0), 0),
+      entitled_remaining_units: entitlements.reduce((sum, entry) => sum + Number(entry.remaining_units || 0), 0)
+    },
+    linked_surfaces: {
+      spend_credentials_ref: `/v1/spend-credentials?account_id=${encodeURIComponent(accountId)}`,
+      external_credit_grants_ref: `/v1/credit-bridge/grants?account_id=${encodeURIComponent(accountId)}`,
+      entitlements_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/entitlements`,
+      policy_summary_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/policy-summary`,
+      authority_bundle_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/authority-bundle`
+    },
+    generated_at_iso: nowIso()
+  };
+}
+
+function buildAuthorityBundle(state, accountId) {
+  const summary = buildAuthoritySummary(state, accountId);
+  const bindings = listAuthorityBindingsForAccount(state, accountId).map((entry) => ({
+    binding_id: entry.binding_id,
+    status: entry.status,
+    authority_kind: entry.authority_kind,
+    spend_posture: entry.spend_posture,
+    scope: entry.scope,
+    authority_scope: ensureArray(entry.authority_scope),
+    allowed_consequence_families: ensureArray(entry.allowed_consequence_families),
+    consequence_bounds: entry.consequence_bounds || {
+      max_commit_units: null,
+      max_reserve_units: null,
+      max_reversal_units: null
+    },
+    credential_id: entry.credential_id || null,
+    agent_id: entry.agent_id || null,
+    budget_id: entry.budget_id || null,
+    pack_id: entry.pack_id || null,
+    entitlement_id: entry.entitlement_id || null,
+    issued_by: entry.issued_by || null,
+    expires_at_iso: entry.expires_at_iso || null
+  }));
+  const credentials = listSpendCredentialsForAccount(state, accountId).map((entry) => ({
+    credential_id: entry.credential_id,
+    status: entry.status,
+    spend_posture: entry.spend_posture,
+    scope: entry.scope,
+    agent_id: entry.agent_id || null,
+    budget_id: entry.budget_id || null,
+    pack_id: entry.pack_id || null,
+    entitlement_id: entry.entitlement_id || null,
+    issued_by: entry.issued_by || null,
+    expires_at_iso: entry.expires_at_iso || null,
+    labels: ensureArray(entry.labels)
+  }));
+  const grants = listExternalCreditGrantsForAccount(state, accountId).map((entry) => ({
+    grant_id: entry.grant_id,
+    status: entry.status,
+    source: entry.source || null,
+    pack_id: entry.pack_id || null,
+    entitlement_id: entry.entitlement_id || null,
+    units: Number(entry.units || 0),
+    provider_reference: entry.provider_reference || null,
+    created_at_iso: entry.created_at_iso || null
+  }));
+  const entitlements = listMapValuesByAccount(state.economicsEntitlements, accountId).map((entry) => ({
+    entitlement_id: entry.entitlement_id,
+    status: entry.status,
+    pack_id: entry.pack_id || null,
+    issued_units: Number(entry.issued_units || 0),
+    consumed_units: Number(entry.consumed_units || 0),
+    remaining_units: Number(entry.remaining_units || 0),
+    preferred_replacement_pack_id: entry.preferred_replacement_pack_id || null
+  }));
+  const agents = listMapValuesByAccount(state.economicsAgents, accountId).map((entry) => ({
+    agent_id: entry.agent_id,
+    status: entry.status,
+    default_budget_id: entry.default_budget_id || null,
+    allowed_job_domains: ensureArray(entry.allowed_job_domains)
+  }));
+  const budgets = listMapValuesByAccount(state.economicsBudgets, accountId).map((entry) => ({
+    budget_id: entry.budget_id,
+    status: entry.status,
+    max_reserve_units: entry.max_reserve_units,
+    policy_ref: entry.policy_ref || null,
+    allowed_job_domains: ensureArray(entry.allowed_job_domains)
+  }));
+
+  return {
+    bundle_version: "xytara-authority-bundle-v1",
+    account_id: accountId,
+    authority_summary: summary,
+    authority_bindings: bindings,
+    delegated_spend_credentials: credentials,
+    external_credit_grants: grants,
+    entitlements,
+    economics_agents: agents,
+    economics_budgets: budgets,
+    authority_tracks: {
+      funding_track: grants.length > 0 ? "external_grant_backed" : "direct_credit_only",
+      delegation_track: bindings.length > 0 ? "authority_binding_available" : credentials.length > 0 ? "delegated_spend_available" : "operator_only_spend",
+      governance_track: agents.length > 0 || budgets.length > 0 ? "policy_bounded" : "unbounded"
+    },
+    linked_surfaces: {
+      authority_summary_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/authority-summary`,
+      operator_shell_summary_ref: "/v1/operator-shell/summary"
+    },
+    generated_at_iso: nowIso()
+  };
+}
+
+function buildAuthorityUsageSummary(state, accountId) {
+  const bindings = listAuthorityBindingsForAccount(state, accountId);
+  const bindingUsage = bindings.map((binding) => {
+    const delegatedTransactions = listDelegatedTransactionsForCredential(state, binding.credential_id);
+    const usageCount = delegatedTransactions.length;
+    const latestUsedAtIso = delegatedTransactions
+      .map((entry) => entry.created_at_iso || null)
+      .filter(Boolean)
+      .sort()
+      .slice(-1)[0] || null;
+    return {
+      binding_id: binding.binding_id,
+      credential_id: binding.credential_id || null,
+      status: binding.status,
+      authority_scope: ensureArray(binding.authority_scope),
+      delegated_transaction_count: usageCount,
+      latest_used_at_iso: latestUsedAtIso
+    };
+  });
+
+  return {
+    summary_version: "xytara-authority-usage-summary-v1",
+    account_id: accountId,
+    authority_binding_count: bindings.length,
+    active_authority_binding_count: bindings.filter((entry) => entry.status === "active").length,
+    used_authority_binding_count: bindingUsage.filter((entry) => entry.delegated_transaction_count > 0).length,
+    total_delegated_transaction_count: bindingUsage.reduce((sum, entry) => sum + entry.delegated_transaction_count, 0),
+    bindings: bindingUsage,
+    linked_surfaces: {
+      authority_summary_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/authority-summary`,
+      authority_bundle_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/authority-bundle`,
+      authority_review_bundle_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/authority-review-bundle`
+    },
+    generated_at_iso: nowIso()
+  };
+}
+
+function buildAuthorityReviewBundle(state, accountId) {
+  const summary = buildAuthoritySummary(state, accountId);
+  const usage = buildAuthorityUsageSummary(state, accountId);
+  const reviewRows = usage.bindings.map((bindingUsage) => {
+    const matchingBinding = listAuthorityBindingsForAccount(state, accountId).find((entry) => entry.binding_id === bindingUsage.binding_id) || null;
+    const scopeCount = bindingUsage.authority_scope.length;
+    const consequenceBounds = matchingBinding && matchingBinding.consequence_bounds ? matchingBinding.consequence_bounds : {};
+    const broadOpenSpend = matchingBinding && matchingBinding.spend_posture === "open_spend" && scopeCount > 1;
+    const quietBinding = bindingUsage.delegated_transaction_count === 0;
+    const missingBounds = !Number.isFinite(Number(consequenceBounds.max_commit_units));
+    const reviewState = broadOpenSpend || missingBounds ? "tighten_candidate" : quietBinding ? "rotate_or_revoke_candidate" : "healthy";
+    return {
+      binding_id: bindingUsage.binding_id,
+      credential_id: bindingUsage.credential_id,
+      review_state: reviewState,
+      delegated_transaction_count: bindingUsage.delegated_transaction_count,
+      authority_scope_count: scopeCount,
+      latest_used_at_iso: bindingUsage.latest_used_at_iso,
+      recommended_action: reviewState === "tighten_candidate"
+        ? "tighten_scope_or_bounds"
+        : reviewState === "rotate_or_revoke_candidate"
+          ? "review_for_rotation_or_revocation"
+          : "keep_active"
+    };
+  });
+
+  return {
+    bundle_version: "xytara-authority-review-bundle-v1",
+    account_id: accountId,
+    authority_summary: summary,
+    authority_usage_summary: usage,
+    review_rows: reviewRows,
+    review_counts: {
+      tighten_candidate_count: reviewRows.filter((entry) => entry.review_state === "tighten_candidate").length,
+      rotate_or_revoke_candidate_count: reviewRows.filter((entry) => entry.review_state === "rotate_or_revoke_candidate").length,
+      healthy_count: reviewRows.filter((entry) => entry.review_state === "healthy").length
+    },
+    linked_surfaces: {
+      authority_summary_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/authority-summary`,
+      authority_usage_summary_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/authority-usage-summary`
+    },
+    generated_at_iso: nowIso()
+  };
+}
+
+function buildAuthorityAttentionSummary(state, accountId) {
+  const reviewBundle = buildAuthorityReviewBundle(state, accountId);
+  const attentionRows = reviewBundle.review_rows
+    .filter((entry) => entry.review_state !== "healthy")
+    .map((entry) => ({
+      binding_id: entry.binding_id,
+      credential_id: entry.credential_id,
+      review_state: entry.review_state,
+      delegated_transaction_count: entry.delegated_transaction_count,
+      latest_used_at_iso: entry.latest_used_at_iso,
+      recommended_action: entry.recommended_action
+    }));
+
+  return {
+    summary_version: "xytara-authority-attention-summary-v1",
+    account_id: accountId,
+    overall_attention_state: attentionRows.length > 0 ? "attention_required" : "healthy",
+    attention_binding_count: attentionRows.length,
+    review_counts: reviewBundle.review_counts,
+    attention_rows: attentionRows,
+    linked_surfaces: {
+      authority_review_bundle_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/authority-review-bundle`,
+      authority_usage_summary_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/authority-usage-summary`
+    },
+    generated_at_iso: nowIso()
+  };
+}
+
+function buildAuthorityLineageSummary(state, accountId) {
+  const bindings = listAuthorityBindingsForAccount(state, accountId);
+  const bindingIds = new Set(bindings.map((entry) => entry.binding_id));
+  const lineageRows = bindings.map((entry) => {
+    const predecessorId = normalizeString(entry.rotated_from_binding_id, null);
+    const successorId = normalizeString(entry.replaced_by_binding_id, null);
+    return {
+      binding_id: entry.binding_id,
+      status: entry.status,
+      credential_id: entry.credential_id || null,
+      predecessor_binding_id: predecessorId,
+      successor_binding_id: successorId,
+      lineage_position: predecessorId ? successorId ? "middle" : "leaf" : successorId ? "root" : "standalone",
+      predecessor_known: predecessorId ? bindingIds.has(predecessorId) : false,
+      successor_known: successorId ? bindingIds.has(successorId) : false,
+      rotated_at_iso: entry.revoked_at_iso || null,
+      created_at_iso: entry.created_at_iso || null,
+      updated_at_iso: entry.updated_at_iso || null
+    };
+  });
+
+  const roots = lineageRows.filter((entry) => entry.lineage_position === "root" || entry.lineage_position === "standalone");
+  const leaves = lineageRows.filter((entry) => entry.lineage_position === "leaf" || entry.lineage_position === "standalone");
+
+  return {
+    summary_version: "xytara-authority-lineage-summary-v1",
+    account_id: accountId,
+    authority_binding_count: bindings.length,
+    rotated_binding_count: lineageRows.filter((entry) => entry.predecessor_binding_id || entry.successor_binding_id).length,
+    root_binding_count: roots.length,
+    leaf_binding_count: leaves.length,
+    lineage_rows: lineageRows,
+    linked_surfaces: {
+      authority_bundle_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/authority-bundle`,
+      authority_review_bundle_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/authority-review-bundle`,
+      authority_attention_summary_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/authority-attention-summary`
+    },
+    generated_at_iso: nowIso()
+  };
+}
+
+function buildAuthorityPolicyPack(state, accountId) {
+  const summary = buildAuthoritySummary(state, accountId);
+  const review = buildAuthorityReviewBundle(state, accountId);
+  const attention = buildAuthorityAttentionSummary(state, accountId);
+  const lineage = buildAuthorityLineageSummary(state, accountId);
+  const templates = [
+    {
+      template_id: "runtime_builder_default",
+      authority_scope: ["runtime.execute", "economics.consume"],
+      allowed_consequence_families: ["commit", "meter"],
+      consequence_bounds: {
+        max_commit_units: 25,
+        max_reserve_units: null,
+        max_reversal_units: 0
+      },
+      recommended_for: "runtime-first delegated execution"
+    },
+    {
+      template_id: "reserve_operator_bounded",
+      authority_scope: ["economics.reserve", "economics.release"],
+      allowed_consequence_families: ["reserve", "release"],
+      consequence_bounds: {
+        max_commit_units: 0,
+        max_reserve_units: 40,
+        max_reversal_units: 0
+      },
+      recommended_for: "bounded treasury-hold operations"
+    },
+    {
+      template_id: "reversal_operator_limited",
+      authority_scope: ["economics.reverse"],
+      allowed_consequence_families: ["reverse"],
+      consequence_bounds: {
+        max_commit_units: 0,
+        max_reserve_units: 0,
+        max_reversal_units: 5
+      },
+      recommended_for: "corrective operator handling"
+    }
+  ];
+
+  return {
+    pack_version: "xytara-authority-policy-pack-v1",
+    account_id: accountId,
+    authority_summary: summary,
+    review_counts: review.review_counts,
+    overall_attention_state: attention.overall_attention_state,
+    lineage_overview: {
+      authority_binding_count: lineage.authority_binding_count,
+      rotated_binding_count: lineage.rotated_binding_count,
+      root_binding_count: lineage.root_binding_count,
+      leaf_binding_count: lineage.leaf_binding_count
+    },
+    recommended_policy_motion: attention.attention_binding_count > 0 ? "tighten_or_rotate_existing_bindings" : "issue_from_template",
+    policy_templates: templates,
+    linked_surfaces: {
+      authority_bundle_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/authority-bundle`,
+      authority_review_bundle_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/authority-review-bundle`,
+      authority_attention_summary_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/authority-attention-summary`,
+      authority_lineage_summary_ref: `/v1/economics/accounts/${encodeURIComponent(accountId)}/authority-lineage-summary`
+    },
+    generated_at_iso: nowIso()
+  };
+}
+
+function buildAuthorityPolicyPackSummary(state, accountId) {
+  const pack = buildAuthorityPolicyPack(state, accountId);
+  return {
+    summary_version: "xytara-authority-policy-pack-summary-v1",
+    account_id: accountId,
+    recommended_policy_motion: pack.recommended_policy_motion,
+    template_count: Array.isArray(pack.policy_templates) ? pack.policy_templates.length : 0,
+    overall_attention_state: pack.overall_attention_state,
+    rotated_binding_count: pack.lineage_overview.rotated_binding_count,
+    linked_surfaces: pack.linked_surfaces,
+    generated_at_iso: pack.generated_at_iso
+  };
+}
+
+module.exports = {
+  buildAuthoritySummary,
+  buildAuthorityBundle,
+  buildAuthorityUsageSummary,
+  buildAuthorityReviewBundle,
+  buildAuthorityAttentionSummary,
+  buildAuthorityLineageSummary,
+  buildAuthorityPolicyPack,
+  buildAuthorityPolicyPackSummary
+};