xytara 2.4.0 → 2.5.0

package/lib/asyncapi_contract.js

@@ -0,0 +1,150 @@
+"use strict";
+
+const pkg = require("../package.json");
+
+function buildAsyncApiDocument() {
+  return {
+    asyncapi: "3.0.0",
+    info: {
+      title: "xytara Event Contract",
+      version: pkg.version,
+      summary: "Machine-commerce runtime event and handoff contract.",
+      description: "This AsyncAPI document describes the stable runtime event and handoff surfaces that outside builders and partners should rely on first."
+    },
+    servers: {
+      httpRuntime: {
+        host: "127.0.0.1:4320",
+        protocol: "http",
+        description: "Local xytara HTTP event and handoff entrypoint"
+      }
+    },
+    channels: {
+      "runtime/events/emit": {
+        address: "/v1/runtime/emit",
+        messages: {
+          runtimeEmitRequest: {
+            name: "runtimeEmitRequest",
+            title: "Runtime emit request",
+            summary: "Append a runtime event record."
+          }
+        }
+      },
+      "runtime/events/anchor": {
+        address: "/v1/runtime/anchor",
+        messages: {
+          runtimeAnchorRequest: {
+            name: "runtimeAnchorRequest",
+            title: "Runtime anchor request",
+            summary: "Anchor a runtime event into registry/anchor posture."
+          }
+        }
+      },
+      "runtime/events/emit-anchor": {
+        address: "/v1/runtime/emit-anchor",
+        messages: {
+          runtimeEmitAnchorRequest: {
+            name: "runtimeEmitAnchorRequest",
+            title: "Runtime emit-anchor request",
+            summary: "Emit and anchor a runtime event in one call."
+          }
+        }
+      },
+      "handoffs/trust/emit": {
+        address: "/v1/trust/handoffs/emit",
+        messages: {
+          trustHandoffEmitRequest: {
+            name: "trustHandoffEmitRequest",
+            title: "Trust handoff emit request",
+            summary: "Emit a trust-compatible handoff bundle."
+          }
+        }
+      },
+      "handoffs/execution-receipts/emit": {
+        address: "/v1/execution-receipts/handoffs/emit",
+        messages: {
+          executionReceiptHandoffEmitRequest: {
+            name: "executionReceiptHandoffEmitRequest",
+            title: "Execution receipt handoff emit request",
+            summary: "Emit an execution receipt handoff bundle."
+          }
+        }
+      },
+      "handoffs/receipt-ledger/emit": {
+        address: "/v1/receipt-ledger/handoffs/emit",
+        messages: {
+          receiptLedgerHandoffEmitRequest: {
+            name: "receiptLedgerHandoffEmitRequest",
+            title: "Receipt ledger handoff emit request",
+            summary: "Emit a receipt-ledger handoff bundle."
+          }
+        }
+      }
+    },
+    operations: {
+      publishRuntimeEvent: {
+        action: "send",
+        channel: { $ref: "#/channels/runtime/events/emit" },
+        summary: "Publish runtime event data through the stable emit surface."
+      },
+      publishRuntimeAnchor: {
+        action: "send",
+        channel: { $ref: "#/channels/runtime/events/anchor" },
+        summary: "Publish anchoring data through the stable anchor surface."
+      },
+      publishRuntimeEmitAnchor: {
+        action: "send",
+        channel: { $ref: "#/channels/runtime/events/emit-anchor" },
+        summary: "Publish combined emit-anchor data through the stable combined surface."
+      },
+      publishTrustHandoff: {
+        action: "send",
+        channel: { $ref: "#/channels/handoffs/trust/emit" },
+        summary: "Publish trust handoff data for proof followthrough."
+      },
+      publishExecutionReceiptHandoff: {
+        action: "send",
+        channel: { $ref: "#/channels/handoffs/execution-receipts/emit" },
+        summary: "Publish execution receipt handoff data."
+      },
+      publishReceiptLedgerHandoff: {
+        action: "send",
+        channel: { $ref: "#/channels/handoffs/receipt-ledger/emit" },
+        summary: "Publish receipt-ledger handoff data."
+      }
+    },
+    "x-naxytra-contract": {
+      product: "xytara",
+      stability: "stable_public_event_layer",
+      channel_count: 6,
+      linked_docs: [
+        "SERVICE_CONTRACT.md",
+        "FINAL_CONTRACT.md",
+        "START_HERE.md"
+      ]
+    }
+  };
+}
+
+function summarizeAsyncApiDocument() {
+  const document = buildAsyncApiDocument();
+  return {
+    product: "xytara",
+    category: "machine-commerce-asyncapi-contract-summary",
+    summary_version: "xytara-asyncapi-contract-summary-v1",
+    asyncapi_version: document.asyncapi,
+    info_version: document.info.version,
+    channel_count: Object.keys(document.channels).length,
+    operation_count: Object.keys(document.operations).length,
+    primary_event_lanes: ["runtime", "handoff"],
+    linked_surfaces: {
+      asyncapi_ref: "/asyncapi.json",
+      service_contract_ref: "SERVICE_CONTRACT.md",
+      openapi_ref: "/openapi.json"
+    }
+  };
+}
+
+module.exports = {
+  buildAsyncApiDocument,
+  summarizeAsyncApiDocument
+};

package/lib/auth_interop_contract.js

@@ -0,0 +1,80 @@
+"use strict";
+
+const pkg = require("../package.json");
+
+function buildAuthInteropContract() {
+  return {
+    product: "xytara",
+    category: "machine-commerce-auth-interop-contract",
+    contract_version: "xytara-auth-interop-contract-v1",
+    service_version: pkg.version,
+    primary_posture: "native_authority_with_oauth_oidc_token_exchange_interop",
+    supported_interop_profiles: [
+      {
+        profile_id: "oauth_client_credentials_runtime",
+        standards: ["oauth_2_0", "oidc_optional"],
+        intended_use: "machine-to-machine runtime invocation",
+        primary_routes: ["/v1/commands/execute", "/v1/mcp/tools/invoke"]
+      },
+      {
+        profile_id: "bounded_delegation_token_exchange",
+        standards: ["oauth_2_0_token_exchange", "jwt_bearer_optional"],
+        intended_use: "map upstream bearer posture into bounded delegated authority",
+        primary_routes: [
+          "/v1/account-auth/spend-credentials",
+          "/v1/account-auth/authority-bindings",
+          "/v1/commands/execute"
+        ]
+      },
+      {
+        profile_id: "mcp_a2a_a2c_interop_auth",
+        standards: ["oauth_2_0", "oidc", "token_exchange_optional"],
+        intended_use: "protocol-lane authentication for MCP, A2A, and A2C usage",
+        primary_routes: ["/v1/mcp/tools/invoke", "/x402/mcp/tools/invoke", "/v1/commands/execute"]
+      },
+      {
+        profile_id: "x402_payment_plus_bounded_auth",
+        standards: ["oauth_2_0_optional", "x402"],
+        intended_use: "combine payment challenge posture with bounded authenticated execution",
+        primary_routes: ["/x402/mcp/tools/invoke", "/x402/commands/execute"]
+      }
+    ],
+    native_authority_mapping: {
+      authority_bindings: "/v1/account-auth/authority-bindings",
+      spend_credentials: "/v1/account-auth/spend-credentials",
+      execution_entry: "/v1/commands/execute",
+      mcp_entry: "/v1/mcp/tools/invoke"
+    },
+    guardrails: [
+      "native authority bindings remain canonical for bounded execution",
+      "oauth or oidc interop must not replace native consequence bounds",
+      "token exchange may map into delegation but must not bypass authority contracts",
+      "payment verification and auth posture remain separate concerns even when combined in one flow"
+    ],
+    linked_surfaces: {
+      openapi_ref: "/openapi.json",
+      asyncapi_ref: "/asyncapi.json",
+      cloudevents_ref: "/cloudevents.json",
+      service_contract_ref: "SERVICE_CONTRACT.md"
+    }
+  };
+}
+
+function summarizeAuthInteropContract() {
+  const contract = buildAuthInteropContract();
+  return {
+    product: "xytara",
+    category: "machine-commerce-auth-interop-contract-summary",
+    summary_version: "xytara-auth-interop-contract-summary-v1",
+    contract_version: contract.contract_version,
+    profile_count: contract.supported_interop_profiles.length,
+    primary_posture: contract.primary_posture,
+    primary_protocol_lanes: ["mcp", "a2a", "a2c", "x402"],
+    linked_surfaces: contract.linked_surfaces
+  };
+}
+
+module.exports = {
+  buildAuthInteropContract,
+  summarizeAuthInteropContract
+};

package/lib/cloudevents_contract.js

@@ -0,0 +1,80 @@
+"use strict";
+
+const pkg = require("../package.json");
+
+function buildCloudEventsContract() {
+  return {
+    product: "xytara",
+    category: "machine-commerce-cloudevents-contract",
+    contract_version: "xytara-cloudevents-contract-v1",
+    specversion: "1.0",
+    service_version: pkg.version,
+    envelope: {
+      required_attributes: ["specversion", "id", "source", "type", "time", "subject", "datacontenttype", "data"],
+      datacontenttype_default: "application/json",
+      source_prefix: "urn:naxytra:xytara",
+      id_shape: "evt_<opaque_id>",
+      time_format: "RFC3339"
+    },
+    event_families: [
+      {
+        type: "io.naxytra.xytara.runtime.emitted",
+        source: "urn:naxytra:xytara:runtime",
+        subject: "runtime.event"
+      },
+      {
+        type: "io.naxytra.xytara.runtime.anchored",
+        source: "urn:naxytra:xytara:runtime",
+        subject: "runtime.anchor"
+      },
+      {
+        type: "io.naxytra.xytara.handoff.trust.emitted",
+        source: "urn:naxytra:xytara:handoff",
+        subject: "handoff.trust"
+      },
+      {
+        type: "io.naxytra.xytara.handoff.execution_receipt.emitted",
+        source: "urn:naxytra:xytara:handoff",
+        subject: "handoff.execution_receipt"
+      },
+      {
+        type: "io.naxytra.xytara.handoff.receipt_ledger.emitted",
+        source: "urn:naxytra:xytara:handoff",
+        subject: "handoff.receipt_ledger"
+      }
+    ],
+    stable_http_surfaces: [
+      "/v1/runtime/emit",
+      "/v1/runtime/anchor",
+      "/v1/runtime/emit-anchor",
+      "/v1/trust/handoffs/emit",
+      "/v1/execution-receipts/handoffs/emit",
+      "/v1/receipt-ledger/handoffs/emit"
+    ],
+    linked_surfaces: {
+      openapi_ref: "/openapi.json",
+      asyncapi_ref: "/asyncapi.json",
+      service_contract_ref: "SERVICE_CONTRACT.md"
+    }
+  };
+}
+
+function summarizeCloudEventsContract() {
+  const contract = buildCloudEventsContract();
+  return {
+    product: "xytara",
+    category: "machine-commerce-cloudevents-contract-summary",
+    summary_version: "xytara-cloudevents-contract-summary-v1",
+    specversion: contract.specversion,
+    contract_version: contract.contract_version,
+    event_family_count: contract.event_families.length,
+    stable_surface_count: contract.stable_http_surfaces.length,
+    primary_event_lanes: ["runtime", "handoff"],
+    linked_surfaces: contract.linked_surfaces
+  };
+}
+
+module.exports = {
+  buildCloudEventsContract,
+  summarizeCloudEventsContract
+};

package/lib/commerce_client.js

@@ -2003,6 +2003,38 @@ class CommerceClient {
     return result && result.data ? result.data : { ok: false, reason: "invalid_promotion_action_request" };
   }
 
+  async getProviderLane() {
+    return this.getJson("/v1/providers");
+  }
+
+  async getProviderLaneSummary() {
+    return this.getJson("/v1/providers/summary");
+  }
+
+  async getFrameworkLane() {
+    return this.getJson("/v1/frameworks");
+  }
+
+  async getFrameworkLaneSummary() {
+    return this.getJson("/v1/frameworks/summary");
+  }
+
+  async getProtocolLane() {
+    return this.getJson("/v1/protocols");
+  }
+
+  async getProtocolLaneSummary() {
+    return this.getJson("/v1/protocols/summary");
+  }
+
+  async getIntegrationMatrix() {
+    return this.getJson("/v1/integration-matrix");
+  }
+
+  async getIntegrationMatrixSummary() {
+    return this.getJson("/v1/integration-matrix/summary");
+  }
+
   async getTaskExecutionModeSummaries(forceRefresh) {
     const tasks = await this.listTasks(forceRefresh);
     return summarizeFacetCounts(

package/lib/erc8004_lane_contract.js

@@ -0,0 +1,65 @@
+"use strict";
+
+const {
+  buildPhase4Erc8004RuntimePack,
+  summarizePhase4Erc8004RuntimePack
+} = require("./phase_4_erc8004_runtime_pack");
+
+function buildErc8004LanePack() {
+  const phasePack = buildPhase4Erc8004RuntimePack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-erc8004-lane-pack",
+    pack_version: "xytara-erc8004-lane-pack-v1",
+    lane_state: "first_party_erc8004_runtime_present",
+    posture: "identity_and_attestation_runtime_interop_lane",
+    phase_alignment: {
+      phase_ref: phasePack.phase_ref,
+      phase_runtime_pack: phasePack,
+      phase_runtime_summary: summarizePhase4Erc8004RuntimePack()
+    },
+    supported_surfaces: {
+      phase_runtime_ref: "/v1/phases/phase-4/erc8004",
+      phase_runtime_summary_ref: "/v1/phases/phase-4/erc8004/summary",
+      identity_interop_ref: "/v1/identity-interop",
+      machine_identity_summary_ref_template: "/v1/economics/accounts/:account_id/machine-identity-summary",
+      machine_identity_profile_ref_template: "/v1/economics/accounts/:account_id/machine-identity-profile",
+      authority_summary_ref_template: "/v1/economics/accounts/:account_id/authority-summary"
+    },
+    first_run_flows: [
+      {
+        flow_ref: "erc8004.identity_attestation_runtime_view",
+        recommended_reason: "best first runtime-facing trust lane for identity, policy carry, and wallet resolution posture",
+        sequence: [
+          "inspect_erc8004_lane_summary",
+          "inspect_identity_interop_contract",
+          "inspect_machine_identity_summary",
+          "inspect_authority_and_policy_carry"
+        ]
+      }
+    ],
+    guardrails: [
+      "erc8004 is an interop lane rather than the canonical source of runtime authority truth",
+      "native machine identity and authority remain canonical inside xytara",
+      "erc8004 posture should improve partner trust and portability without bloating the runtime core"
+    ]
+  };
+}
+
+function summarizeErc8004LanePack() {
+  const pack = buildErc8004LanePack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-erc8004-lane-pack-summary",
+    summary_version: "xytara-erc8004-lane-pack-summary-v1",
+    lane_state: pack.lane_state,
+    posture: pack.posture,
+    first_run_flow_count: pack.first_run_flows.length,
+    linked_surfaces: pack.supported_surfaces
+  };
+}
+
+module.exports = {
+  buildErc8004LanePack,
+  summarizeErc8004LanePack
+};

package/lib/event_system_lane_contract.js

@@ -0,0 +1,75 @@
+"use strict";
+
+const {
+  buildPhase7EventSystemPack,
+  summarizePhase7EventSystemPack
+} = require("./phase_7_event_system_pack");
+const {
+  buildPhase7NatsRuntimePack,
+  summarizePhase7NatsRuntimePack
+} = require("./phase_7_nats_runtime_pack");
+
+function buildEventSystemLanePack() {
+  const phasePack = buildPhase7EventSystemPack();
+  const natsPack = buildPhase7NatsRuntimePack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-event-system-lane-pack",
+    pack_version: "xytara-event-system-lane-pack-v1",
+    lane_state: "first_party_event_system_family_present",
+    posture: "event_and_system_integration_runtime_lane",
+    phase_alignment: {
+      phase_ref: phasePack.phase_ref,
+      phase_pack: phasePack,
+      phase_summary: summarizePhase7EventSystemPack(),
+      featured_lane: {
+        pack: natsPack,
+        summary: summarizePhase7NatsRuntimePack()
+      }
+    },
+    supported_surfaces: {
+      phase_summary_ref: "/v1/phases/phase-7/summary",
+      nats_runtime_summary_ref: "/v1/phases/phase-7/nats/summary",
+      kafka_runtime_summary_ref: "/v1/phases/phase-7/kafka/summary",
+      mqtt_runtime_summary_ref: "/v1/phases/phase-7/mqtt/summary",
+      webhook_runtime_summary_ref: "/v1/phases/phase-7/webhook-event-bus/summary",
+      continuity_summary_ref: "/v1/phases/phase-7/event-system-continuity/summary",
+      asyncapi_ref: "/asyncapi.json",
+      cloudevents_ref: "/cloudevents.json"
+    },
+    first_run_flows: [
+      {
+        flow_ref: "nats_subject_mesh_runtime",
+        recommended_reason: "best first durable event/system lane for subject-oriented machine coordination with NATS plus JetStream-style persistence posture",
+        sequence: [
+          "inspect_event_system_lane_summary",
+          "inspect_nats_runtime_summary",
+          "inspect_asyncapi_and_cloudevents_contracts",
+          "choose_broker_or_callback_family_for_the_integration"
+        ]
+      }
+    ],
+    guardrails: [
+      "event-system lanes extend runtime coordination rather than replace the default transaction flow",
+      "nats and jetstream style durability should improve integration fit without widening the public runtime core into a generic bus platform"
+    ]
+  };
+}
+
+function summarizeEventSystemLanePack() {
+  const pack = buildEventSystemLanePack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-event-system-lane-pack-summary",
+    summary_version: "xytara-event-system-lane-pack-summary-v1",
+    lane_state: pack.lane_state,
+    posture: pack.posture,
+    first_run_flow_count: pack.first_run_flows.length,
+    linked_surfaces: pack.supported_surfaces
+  };
+}
+
+module.exports = {
+  buildEventSystemLanePack,
+  summarizeEventSystemLanePack
+};

package/lib/feature_control_lane_contract.js

@@ -0,0 +1,54 @@
+"use strict";
+
+function buildFeatureControlLanePack() {
+  return {
+    product: "xytara",
+    category: "machine-commerce-feature-control-lane-pack",
+    pack_version: "xytara-feature-control-lane-pack-v1",
+    lane_state: "first_party_feature_control_lane_present",
+    posture: "portable_policy_and_rollout_control_lane",
+    standards: ["openfeature", "ofrep"],
+    focal_controls: ["pricing_policy", "authority_policy", "machine_identity_policy", "trust_policy", "release_candidate_gates"],
+    supported_surfaces: {
+      pricing_policy_ref: "/v1/economics/accounts/:account_id/pricing-policy-package",
+      authority_policy_ref: "/v1/economics/accounts/:account_id/authority-policy-pack",
+      machine_identity_policy_ref: "/v1/economics/accounts/:account_id/machine-identity-policy-pack",
+      trust_policy_ref: "/v1/economics/accounts/:account_id/trust-layer-policy-pack",
+      release_candidate_ref: "/v1/release-candidate"
+    },
+    first_run_flows: [
+      {
+        flow_ref: "portable_rollout_control_alignment",
+        recommended_reason: "best path for teams that need portable rollout and policy posture without inventing a second control plane around the runtime",
+        sequence: [
+          "inspect_feature_control_lane_summary",
+          "map native policy packs to portable feature-control posture",
+          "use release and trust gates as rollout-compatible control surfaces",
+          "keep xytara policy truth canonical beneath external control adapters"
+        ]
+      }
+    ],
+    guardrails: [
+      "feature control should expose rollout posture without replacing native pricing, authority, identity, or trust truth",
+      "policy portability should remain bounded to avoid accidental split-brain control semantics"
+    ]
+  };
+}
+
+function summarizeFeatureControlLanePack() {
+  const pack = buildFeatureControlLanePack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-feature-control-lane-pack-summary",
+    summary_version: "xytara-feature-control-lane-pack-summary-v1",
+    lane_state: pack.lane_state,
+    standard_count: pack.standards.length,
+    focal_control_count: pack.focal_controls.length,
+    linked_surfaces: pack.supported_surfaces
+  };
+}
+
+module.exports = {
+  buildFeatureControlLanePack,
+  summarizeFeatureControlLanePack
+};

package/lib/framework_lane_contract.js

@@ -0,0 +1,89 @@
+"use strict";
+
+const {
+  buildPhase6FrameworkRuntimePack,
+  summarizePhase6FrameworkRuntimePack
+} = require("./phase_6_framework_runtime_pack");
+const {
+  summarizePhase6LanggraphRuntimePack
+} = require("./phase_6_langgraph_runtime_pack");
+const {
+  summarizePhase6LangchainRuntimePack
+} = require("./phase_6_langchain_runtime_pack");
+const {
+  summarizePhase6AutogenRuntimePack
+} = require("./phase_6_autogen_runtime_pack");
+const {
+  summarizePhase6SemanticKernelRuntimePack
+} = require("./phase_6_semantic_kernel_runtime_pack");
+
+function buildFrameworkLanePack() {
+  return {
+    product: "xytara",
+    category: "machine-commerce-framework-lane-pack",
+    pack_version: "xytara-framework-lane-pack-v1",
+    lane_state: "first_party_framework_family_present",
+    posture: "framework_orchestration_and_execution_family",
+    framework_family: {
+      pack: buildPhase6FrameworkRuntimePack(),
+      summary: summarizePhase6FrameworkRuntimePack()
+    },
+    featured_frameworks: {
+      langgraph: summarizePhase6LanggraphRuntimePack(),
+      langchain: summarizePhase6LangchainRuntimePack(),
+      autogen: summarizePhase6AutogenRuntimePack(),
+      semantic_kernel: summarizePhase6SemanticKernelRuntimePack()
+    },
+    registry_backed_frameworks: {
+      crewai: {
+        framework_id: "crewai",
+        posture: "registry-backed multi-agent workflow interoperability lane",
+        integration_ref: "builtin.execution.crewai"
+      },
+      llamaindex: {
+        framework_id: "llamaindex",
+        posture: "registry-backed retrieval and agent interoperability lane",
+        integration_ref: "builtin.execution.llamaindex"
+      }
+    },
+    supported_surfaces: {
+      phase_6_summary_ref: "/v1/phases/phase-6/summary",
+      langgraph_summary_ref: "/v1/phases/phase-6/langgraph/summary",
+      langchain_summary_ref: "/v1/phases/phase-6/langchain/summary",
+      autogen_summary_ref: "/v1/phases/phase-6/autogen/summary",
+      semantic_kernel_summary_ref: "/v1/phases/phase-6/semantic-kernel/summary",
+      integrations_ref: "/v1/integrations",
+      integration_matrix_ref: "/v1/integration-matrix"
+    },
+    first_run_flows: [
+      {
+        flow_ref: "framework_family_selection",
+        recommended_reason: "best first path for understanding how orchestration frameworks map into the canonical runtime instead of sitting as disconnected side examples",
+        sequence: [
+          "inspect_framework_lane_summary",
+          "inspect_phase_6_framework_summary",
+          "inspect_named_framework_profiles",
+          "choose_framework_shape_that_best_matches_runtime_carry_needs"
+        ]
+      }
+    ]
+  };
+}
+
+function summarizeFrameworkLanePack() {
+  const pack = buildFrameworkLanePack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-framework-lane-pack-summary",
+    summary_version: "xytara-framework-lane-pack-summary-v1",
+    lane_state: pack.lane_state,
+    featured_framework_count: Object.keys(pack.featured_frameworks).length + Object.keys(pack.registry_backed_frameworks).length,
+    first_run_flow_count: pack.first_run_flows.length,
+    linked_surfaces: pack.supported_surfaces
+  };
+}
+
+module.exports = {
+  buildFrameworkLanePack,
+  summarizeFrameworkLanePack
+};