xytara 2.3.0 → 2.5.0

package/lib/mcp_lane_contract.js

@@ -0,0 +1,110 @@
+"use strict";
+
+const {
+  buildDefaultTransactionCenter,
+  buildDefaultTransactionTaskPackCatalog,
+  buildDefaultTransactionGuidedLoopCatalog,
+  summarizeDefaultTransactionCenter,
+  summarizeDefaultTransactionTaskPacks,
+  summarizeDefaultTransactionGuidedLoops
+} = require("./catalog_contract");
+
+function buildMcpLanePack() {
+  const center = buildDefaultTransactionCenter();
+  const centerSummary = summarizeDefaultTransactionCenter();
+  const taskPackCatalog = buildDefaultTransactionTaskPackCatalog();
+  const taskPackSummary = summarizeDefaultTransactionTaskPacks();
+  const guidedLoopCatalog = buildDefaultTransactionGuidedLoopCatalog();
+  const guidedLoopSummary = summarizeDefaultTransactionGuidedLoops();
+  const taskPacks = Array.isArray(taskPackCatalog.packs) ? taskPackCatalog.packs : [];
+  const guidedLoops = Array.isArray(guidedLoopCatalog.loops) ? guidedLoopCatalog.loops : [];
+  const defaultTaskPack = taskPacks.find((entry) => entry.pack_ref === "default.mcp.tool.invoke") || null;
+  const defaultLoop = guidedLoops.find((entry) => entry.loop_ref === "default.mcp.loop") || null;
+
+  return {
+    product: "xytara",
+    category: "machine-commerce-mcp-lane-pack",
+    pack_version: "xytara-mcp-lane-pack-v1",
+    lane_state: "first_party_default_present",
+    default_protocol: centerSummary.default_protocol,
+    default_payment_protocol: centerSummary.default_payment_protocol,
+    default_settlement_mode: centerSummary.default_settlement_mode,
+    default_transaction_center: center,
+    default_task_pack: defaultTaskPack,
+    default_guided_loop: defaultLoop,
+    task_pack_summary: taskPackSummary,
+    guided_loop_summary: guidedLoopSummary,
+    first_run_tools: [
+      {
+        tool_name: "summarize",
+        lane: "default.mcp.tool.invoke",
+        recommended_reason: "fastest low-friction example tool for first-run usage",
+        example_surfaces: {
+          preview_ref: "/v1/mcp/tools?tool_name=summarize",
+          invoke_ref: "/v1/mcp/tools/invoke"
+        }
+      },
+      {
+        tool_name: "zones.lookup",
+        lane: "default.mcp.loop",
+        recommended_reason: "best first real infrastructure-shaped tool path",
+        example_surfaces: {
+          preview_ref: "/v1/mcp/tools?tool_name=zones.lookup",
+          invoke_ref: "/v1/mcp/tools/invoke"
+        }
+      }
+    ],
+    supported_surfaces: {
+      invoke_ref: "/v1/mcp/tools/invoke",
+      paid_invoke_ref: "/x402/mcp/tools/invoke",
+      auth_profile_ref: "/v1/auth-profiles",
+      openapi_ref: "/openapi.json",
+      asyncapi_ref: "/asyncapi.json",
+      cloudevents_ref: "/cloudevents.json"
+    },
+    recommended_sequence: [
+      "discover_default_mcp_lane",
+      "preview_or_quote_default_tool_path",
+      "choose_native_or_x402_payment_path",
+      "invoke_tool",
+      "inspect_transaction_and_handoff_posture"
+    ]
+  };
+}
+
+function summarizeMcpLanePack() {
+  const pack = buildMcpLanePack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-mcp-lane-pack-summary",
+    summary_version: "xytara-mcp-lane-pack-summary-v1",
+    lane_state: pack.lane_state,
+    default_payment_protocol: pack.default_payment_protocol,
+    default_settlement_mode: pack.default_settlement_mode,
+    first_run_tool_count: pack.first_run_tools.length,
+    guided_loop_ref: pack.default_guided_loop ? pack.default_guided_loop.loop_ref : null,
+    linked_surfaces: pack.supported_surfaces
+  };
+}
+
+function listMcpTools() {
+  return {
+    ok: true,
+    category: "machine-commerce-mcp-tools-list",
+    list_version: "xytara-mcp-tools-list-v1",
+    tools: buildMcpLanePack().first_run_tools
+  };
+}
+
+function getMcpToolDetail(toolName) {
+  const normalizedToolName = String(toolName || "").trim();
+  const tools = buildMcpLanePack().first_run_tools;
+  return tools.find((entry) => entry.tool_name === normalizedToolName) || null;
+}
+
+module.exports = {
+  buildMcpLanePack,
+  summarizeMcpLanePack,
+  listMcpTools,
+  getMcpToolDetail
+};

package/lib/openapi_contract.js

@@ -0,0 +1,296 @@
+"use strict";
+
+const pkg = require("../package.json");
+
+function buildOpenApiDocument() {
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: "xytara Public HTTP Contract",
+      version: pkg.version,
+      summary: "Machine-commerce runtime contract for the stable public HTTP layer.",
+      description: "This OpenAPI document exposes the stable builder-facing HTTP surfaces we want outside builders and partners to stand on first.",
+      contact: {
+        name: "naxytra"
+      }
+    },
+    jsonSchemaDialect: "https://spec.openapis.org/oas/3.1/dialect/base",
+    servers: [
+      {
+        url: "http://127.0.0.1:4320",
+        description: "Local xytara service"
+      }
+    ],
+    tags: [
+      { name: "health", description: "Service health and readiness." },
+      { name: "catalog", description: "Capability discovery surfaces." },
+      { name: "payments", description: "Quote and payment execution surfaces." },
+      { name: "mcp", description: "Machine invocation surfaces." },
+      { name: "authority", description: "Authority and delegation surfaces." },
+      { name: "economics", description: "Wallet, trust, and participation surfaces." },
+      { name: "registry", description: "Capability registry surfaces." }
+    ],
+    paths: {
+      "/health": {
+        get: {
+          tags: ["health"],
+          summary: "Health check",
+          operationId: "getHealth",
+          responses: {
+            "200": {
+              description: "Service health response"
+            }
+          }
+        }
+      },
+      "/v1/catalog": {
+        get: {
+          tags: ["catalog"],
+          summary: "Get capability catalog",
+          operationId: "getCatalog",
+          responses: {
+            "200": { description: "Catalog bundle" }
+          }
+        }
+      },
+      "/v1/catalog/summary": {
+        get: {
+          tags: ["catalog"],
+          summary: "Get capability catalog summary",
+          operationId: "getCatalogSummary",
+          responses: {
+            "200": { description: "Catalog summary" }
+          }
+        }
+      },
+      "/v1/account-auth/spend-credentials": {
+        get: {
+          tags: ["authority"],
+          summary: "List spend credentials",
+          operationId: "listSpendCredentials",
+          responses: {
+            "200": { description: "Spend credential list" }
+          }
+        },
+        post: {
+          tags: ["authority"],
+          summary: "Create spend credential",
+          operationId: "createSpendCredential",
+          responses: {
+            "200": { description: "Spend credential created" }
+          }
+        }
+      },
+      "/v1/payment-quotes": {
+        post: {
+          tags: ["payments"],
+          summary: "Create payment quote",
+          operationId: "createPaymentQuote",
+          responses: {
+            "200": { description: "Quote created" },
+            "400": { description: "Invalid quote request" }
+          }
+        }
+      },
+      "/v1/commands/execute": {
+        post: {
+          tags: ["payments"],
+          summary: "Execute command through the default commerce path",
+          operationId: "executeCommand",
+          responses: {
+            "200": { description: "Execution accepted" },
+            "402": { description: "Payment required or payment challenge" }
+          }
+        }
+      },
+      "/x402/commands/execute": {
+        post: {
+          tags: ["payments"],
+          summary: "Execute command through the x402 payment path",
+          operationId: "executeCommandViaX402",
+          responses: {
+            "200": { description: "Execution accepted" },
+            "402": { description: "x402 payment required" }
+          }
+        }
+      },
+      "/v1/mcp/tools/invoke": {
+        post: {
+          tags: ["mcp"],
+          summary: "Invoke an MCP-facing runtime tool",
+          operationId: "invokeMcpTool",
+          responses: {
+            "200": { description: "Tool invocation result" },
+            "400": { description: "Invalid invocation request" }
+          }
+        }
+      },
+      "/x402/mcp/tools/invoke": {
+        post: {
+          tags: ["mcp"],
+          summary: "Invoke an MCP-facing runtime tool with x402 payment",
+          operationId: "invokeMcpToolViaX402",
+          responses: {
+            "200": { description: "Tool invocation result" },
+            "402": { description: "x402 payment required" }
+          }
+        }
+      },
+      "/v1/economics/accounts/{account_id}/wallet-ledger-bundle": {
+        get: {
+          tags: ["economics"],
+          summary: "Inspect the canonical wallet-ledger bundle",
+          operationId: "getWalletLedgerBundle",
+          parameters: [
+            {
+              name: "account_id",
+              in: "path",
+              required: true,
+              schema: {
+                type: "string"
+              }
+            }
+          ],
+          responses: {
+            "200": { description: "Wallet-ledger bundle" }
+          }
+        }
+      },
+      "/v1/economics/accounts/{account_id}/authority-bundle": {
+        get: {
+          tags: ["authority"],
+          summary: "Inspect canonical account authority posture",
+          operationId: "getAuthorityBundle",
+          parameters: [
+            {
+              name: "account_id",
+              in: "path",
+              required: true,
+              schema: {
+                type: "string"
+              }
+            }
+          ],
+          responses: {
+            "200": { description: "Authority bundle" }
+          }
+        }
+      },
+      "/v1/economics/accounts/{account_id}/machine-identity-operator-bundle": {
+        get: {
+          tags: ["economics"],
+          summary: "Inspect canonical machine identity posture",
+          operationId: "getMachineIdentityOperatorBundle",
+          parameters: [
+            {
+              name: "account_id",
+              in: "path",
+              required: true,
+              schema: {
+                type: "string"
+              }
+            }
+          ],
+          responses: {
+            "200": { description: "Machine identity operator bundle" }
+          }
+        }
+      },
+      "/v1/capability-registry/package": {
+        get: {
+          tags: ["registry"],
+          summary: "Inspect canonical capability registry package",
+          operationId: "getCapabilityRegistryPackage",
+          parameters: [
+            {
+              name: "account_id",
+              in: "query",
+              required: false,
+              schema: {
+                type: "string"
+              }
+            }
+          ],
+          responses: {
+            "200": { description: "Capability registry package" }
+          }
+        }
+      },
+      "/v1/economics/accounts/{account_id}/trust-layer-package": {
+        get: {
+          tags: ["economics"],
+          summary: "Inspect canonical trust-layer package",
+          operationId: "getTrustLayerPackage",
+          parameters: [
+            {
+              name: "account_id",
+              in: "path",
+              required: true,
+              schema: {
+                type: "string"
+              }
+            }
+          ],
+          responses: {
+            "200": { description: "Trust-layer package" }
+          }
+        }
+      },
+      "/v1/economics/accounts/{account_id}/network-participation-package": {
+        get: {
+          tags: ["economics"],
+          summary: "Inspect external network participation package",
+          operationId: "getNetworkParticipationPackage",
+          parameters: [
+            {
+              name: "account_id",
+              in: "path",
+              required: true,
+              schema: {
+                type: "string"
+              }
+            }
+          ],
+          responses: {
+            "200": { description: "Network participation package" }
+          }
+        }
+      }
+    },
+    "x-naxytra-contract": {
+      product: "xytara",
+      stability: "stable_public_http_layer",
+      route_count: 14,
+      target_audience: ["builders", "partners", "operators"],
+      linked_docs: [
+        "SERVICE_CONTRACT.md",
+        "FINAL_CONTRACT.md",
+        "START_HERE.md"
+      ]
+    }
+  };
+}
+
+function summarizeOpenApiDocument() {
+  const document = buildOpenApiDocument();
+  return {
+    product: "xytara",
+    category: "machine-commerce-openapi-contract-summary",
+    summary_version: "xytara-openapi-contract-summary-v1",
+    openapi_version: document.openapi,
+    info_version: document.info.version,
+    path_count: Object.keys(document.paths).length,
+    server_count: document.servers.length,
+    primary_protocol_lanes: ["http", "mcp", "x402"],
+    linked_surfaces: {
+      openapi_ref: "/openapi.json",
+      service_contract_ref: "SERVICE_CONTRACT.md",
+      final_contract_ref: "FINAL_CONTRACT.md"
+    }
+  };
+}
+
+module.exports = {
+  buildOpenApiDocument,
+  summarizeOpenApiDocument
+};

package/lib/protocol_lane_contract.js

@@ -0,0 +1,114 @@
+"use strict";
+
+const { summarizeMcpLanePack } = require("./mcp_lane_contract");
+const { summarizeA2ALanePack } = require("./a2a_lane_contract");
+const { summarizeA2CLanePack } = require("./a2c_lane_contract");
+const { summarizeEventSystemLanePack } = require("./event_system_lane_contract");
+
+function buildProtocolLanePack() {
+  return {
+    product: "xytara",
+    category: "machine-commerce-protocol-lane-pack",
+    pack_version: "xytara-protocol-lane-pack-v1",
+    lane_state: "first_party_protocol_family_present",
+    posture: "canonical_public_view_of_runtime_protocol_and_transport_breadth",
+    featured_protocols: {
+      mcp: {
+        protocol_id: "mcp",
+        posture: "primary_tool_and_capability_invocation_lane",
+        summary: summarizeMcpLanePack(),
+        route_ref: "/v1/mcp"
+      },
+      a2a: {
+        protocol_id: "a2a",
+        posture: "agent_to_agent_negotiation_and_settlement_lane",
+        summary: summarizeA2ALanePack(),
+        route_ref: "/v1/a2a"
+      },
+      a2c: {
+        protocol_id: "a2c",
+        posture: "agent_to_client_tooling_and_session_lane",
+        summary: summarizeA2CLanePack(),
+        route_ref: "/v1/a2c"
+      },
+      acp: {
+        protocol_id: "acp",
+        posture: "adapter_ready_agent_coordination_bridge",
+        route_ref: "/v1/integrations/protocols"
+      },
+      grpc: {
+        protocol_id: "grpc",
+        posture: "adapter_ready_rpc_bridge_for service and system interop",
+        route_ref: "/v1/integrations/protocols"
+      },
+      mqtt: {
+        protocol_id: "mqtt",
+        posture: "event_and_device_oriented bridge lane",
+        route_ref: "/v1/event-systems"
+      },
+      kafka: {
+        protocol_id: "kafka",
+        posture: "durable stream and event bus lane",
+        route_ref: "/v1/event-systems"
+      },
+      nats: {
+        protocol_id: "nats",
+        posture: "subject mesh and jetstream oriented event lane",
+        summary: summarizeEventSystemLanePack(),
+        route_ref: "/v1/event-systems"
+      },
+      ros2: {
+        protocol_id: "ros2",
+        posture: "robotics and embedded coordination bridge",
+        route_ref: "/v1/integrations/protocols"
+      },
+      webhook_event_bus: {
+        protocol_id: "webhook_event_bus",
+        posture: "callback friendly ingress and replay lane",
+        route_ref: "/v1/event-systems"
+      }
+    },
+    supported_surfaces: {
+      mcp_lane_ref: "/v1/mcp",
+      a2a_lane_ref: "/v1/a2a",
+      a2c_lane_ref: "/v1/a2c",
+      event_system_lane_ref: "/v1/event-systems",
+      integration_protocols_ref: "/v1/integrations/protocols",
+      integration_matrix_ref: "/v1/integration-matrix"
+    },
+    first_run_flows: [
+      {
+        flow_ref: "protocol_family_selection",
+        recommended_reason: "best first path for callers who need to understand which invocation, coordination, transport, or callback lane fits their system before wiring payment and settlement",
+        sequence: [
+          "inspect_protocol_lane_summary",
+          "choose_mcp_a2a_or_a2c_for_canonical_runtime_entry",
+          "use_event_or_bridge_protocols_only_when_system_shape_requires_them",
+          "continue_into_payment_and_settlement_selection"
+        ]
+      }
+    ],
+    guardrails: [
+      "protocol breadth should improve fit and adoption without fragmenting the canonical command and payment path",
+      "transport and event bridges remain subordinate to the default runtime and settlement spine"
+    ]
+  };
+}
+
+function summarizeProtocolLanePack() {
+  const pack = buildProtocolLanePack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-protocol-lane-pack-summary",
+    summary_version: "xytara-protocol-lane-pack-summary-v1",
+    lane_state: pack.lane_state,
+    featured_protocol_count: Object.keys(pack.featured_protocols).length,
+    first_run_flow_count: pack.first_run_flows.length,
+    linked_surfaces: pack.supported_surfaces
+  };
+}
+
+module.exports = {
+  buildProtocolLanePack,
+  summarizeProtocolLanePack
+};

package/lib/provenance_lane_contract.js

@@ -0,0 +1,54 @@
+"use strict";
+
+function buildProvenanceLanePack() {
+  return {
+    product: "xytara",
+    category: "machine-commerce-provenance-lane-pack",
+    pack_version: "xytara-provenance-lane-pack-v1",
+    lane_state: "first_party_provenance_lane_present",
+    posture: "release_and_execution_supply_chain_trust_lane",
+    standards: ["slsa"],
+    focal_surfaces: ["release_candidate", "release_manifest", "integration_matrix", "adapter_pack"],
+    supported_surfaces: {
+      release_candidate_ref: "/v1/release-candidate",
+      release_manifest_ref: "/v1/release-manifest",
+      release_center_ref: "/v1/release-center",
+      adapter_pack_ref: "/v1/adapter-pack",
+      integration_matrix_ref: "/v1/integration-matrix"
+    },
+    first_run_flows: [
+      {
+        flow_ref: "release_provenance_review",
+        recommended_reason: "best path for builders and operators who need artifact and release trust before integrating xytara into production systems",
+        sequence: [
+          "inspect_provenance_lane_summary",
+          "inspect_release_candidate_and_manifest",
+          "inspect_adapter_and_integration_breadth",
+          "treat_release_and_adapter posture as provenance-carrying artifacts"
+        ]
+      }
+    ],
+    guardrails: [
+      "provenance should strengthen release trust without turning the runtime into a generic attestation service",
+      "supply-chain trust complements runtime truth and proof truth instead of replacing either"
+    ]
+  };
+}
+
+function summarizeProvenanceLanePack() {
+  const pack = buildProvenanceLanePack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-provenance-lane-pack-summary",
+    summary_version: "xytara-provenance-lane-pack-summary-v1",
+    lane_state: pack.lane_state,
+    standard_count: pack.standards.length,
+    focal_surface_count: pack.focal_surfaces.length,
+    linked_surfaces: pack.supported_surfaces
+  };
+}
+
+module.exports = {
+  buildProvenanceLanePack,
+  summarizeProvenanceLanePack
+};

package/lib/provider_lane_contract.js

@@ -0,0 +1,72 @@
+"use strict";
+
+const {
+  buildPhase1OpenaiCodexRuntimePack,
+  summarizePhase1OpenaiCodexRuntimePack
+} = require("./phase_1_openai_codex_runtime_pack");
+const {
+  buildPhase1ClaudeMcpRuntimePack,
+  summarizePhase1ClaudeMcpRuntimePack
+} = require("./phase_1_claude_mcp_runtime_pack");
+
+function buildProviderLanePack() {
+  return {
+    product: "xytara",
+    category: "machine-commerce-provider-lane-pack",
+    pack_version: "xytara-provider-lane-pack-v1",
+    lane_state: "first_party_provider_family_present",
+    posture: "provider_entry_and_runtime_execution_family",
+    featured_providers: {
+      openai_codex: {
+        pack: buildPhase1OpenaiCodexRuntimePack(),
+        summary: summarizePhase1OpenaiCodexRuntimePack()
+      },
+      claude_mcp: {
+        pack: buildPhase1ClaudeMcpRuntimePack(),
+        summary: summarizePhase1ClaudeMcpRuntimePack()
+      }
+    },
+    supported_surfaces: {
+      phase_1_summary_ref: "/v1/phases/phase-1/summary",
+      openai_codex_summary_ref: "/v1/phases/phase-1/openai-codex/runtime/summary",
+      claude_mcp_summary_ref: "/v1/phases/phase-1/claude-mcp/runtime/summary",
+      mcp_lane_ref: "/v1/mcp",
+      adapter_pack_ref: "/v1/adapter-pack",
+      integrations_ref: "/v1/integrations"
+    },
+    first_run_flows: [
+      {
+        flow_ref: "provider_family_selection",
+        recommended_reason: "best first path for understanding how named provider entry points map into the canonical commerce runtime",
+        sequence: [
+          "inspect_provider_lane_summary",
+          "inspect_openai_codex_and_claude_mcp_profiles",
+          "choose_protocol_and_payment_path",
+          "continue_into_mcp_or_command_execution"
+        ]
+      }
+    ],
+    guardrails: [
+      "provider lanes should stay entry and interoperability shapes rather than redefine the core runtime model",
+      "named providers improve adoption only when they remain subordinate to canonical protocol, payment, and settlement lanes"
+    ]
+  };
+}
+
+function summarizeProviderLanePack() {
+  const pack = buildProviderLanePack();
+  return {
+    product: "xytara",
+    category: "machine-commerce-provider-lane-pack-summary",
+    summary_version: "xytara-provider-lane-pack-summary-v1",
+    lane_state: pack.lane_state,
+    featured_provider_count: Object.keys(pack.featured_providers).length,
+    first_run_flow_count: pack.first_run_flows.length,
+    linked_surfaces: pack.supported_surfaces
+  };
+}
+
+module.exports = {
+  buildProviderLanePack,
+  summarizeProviderLanePack
+};

package/lib/release_history.js

@@ -10,6 +10,22 @@ function buildReleaseHistory() {
     current_version: packageJson.version,
     release_track: "public_release",
     history: [
+      {
+        version: "2.5.0",
+        channel: "public_release",
+        maturity_posture: "adoption_ready",
+        headline: "adoption-surface release with contract lanes, provider and protocol discovery, observability, provenance, artifact distribution, shared signals, and feature-control posture",
+        milestone_refs: [
+          "openapi_asyncapi_cloudevents_contracts",
+          "provider_framework_protocol_lanes",
+          "payment_and_settlement_discovery_lanes",
+          "integration_matrix_and_registry_surfacing",
+          "telemetry_and_provenance_lanes",
+          "artifact_distribution_and_shared_signal_lanes",
+          "feature_control_portability_lanes",
+          "umbrella_cli_entrypoint"
+        ]
+      },
       {
         version: "2.2.0",
         channel: "public_release",