@contractspec/bundle.library 2.9.1 → 3.1.1

package/dist/node/application/mcp/providerRankingMcp.js

@@ -0,0 +1,493 @@
+// src/application/mcp/common.ts
+import { PresentationRegistry } from "@contractspec/lib.contracts-spec/presentations";
+import { createMcpServer } from "@contractspec/lib.contracts-runtime-server-mcp/provider-mcp";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { Elysia } from "elysia";
+import { randomUUID } from "node:crypto";
+var baseCtx = {
+  actor: "anonymous",
+  decide: async () => ({ effect: "allow" })
+};
+function createJsonRpcErrorResponse(status, code, message, data) {
+  return new Response(JSON.stringify({
+    jsonrpc: "2.0",
+    error: {
+      code,
+      message,
+      ...data ? { data } : {}
+    },
+    id: null
+  }), {
+    status,
+    headers: {
+      "content-type": "application/json"
+    }
+  });
+}
+function createSessionState({
+  logger,
+  serverName,
+  ops,
+  resources,
+  prompts,
+  presentations,
+  stateful
+}) {
+  const server = new McpServer({
+    name: serverName,
+    version: "1.0.0"
+  }, {
+    capabilities: {
+      tools: {},
+      resources: {},
+      prompts: {},
+      logging: {}
+    }
+  });
+  logger.info("Setting up MCP server...");
+  createMcpServer(server, ops, resources, prompts, {
+    logger,
+    toolCtx: () => baseCtx,
+    promptCtx: () => ({ locale: "en" }),
+    resourceCtx: () => ({ locale: "en" }),
+    presentations: new PresentationRegistry(presentations)
+  });
+  const transport = new WebStandardStreamableHTTPServerTransport({
+    sessionIdGenerator: stateful ? () => randomUUID() : undefined,
+    enableJsonResponse: true
+  });
+  return server.connect(transport).then(() => ({ server, transport }));
+}
+async function closeSessionState(state) {
+  await Promise.allSettled([state.transport.close(), state.server.close()]);
+}
+function toErrorMessage(error) {
+  return error instanceof Error ? error.stack ?? error.message : String(error);
+}
+function createMcpElysiaHandler({
+  logger,
+  path,
+  serverName,
+  ops,
+  resources,
+  prompts,
+  presentations,
+  validateAuth,
+  requiredAuthMethods
+}) {
+  logger.info("Setting up MCP handler...", {
+    requiredAuthMethods: requiredAuthMethods ?? []
+  });
+  const isStateful = process.env.CONTRACTSPEC_MCP_STATEFUL === "1";
+  const sessions = new Map;
+  async function handleStateless(request) {
+    const state = await createSessionState({
+      logger,
+      path,
+      serverName,
+      ops,
+      resources,
+      prompts,
+      presentations,
+      stateful: false
+    });
+    try {
+      return await state.transport.handleRequest(request);
+    } finally {
+      await closeSessionState(state);
+    }
+  }
+  async function closeSession(sessionId) {
+    const state = sessions.get(sessionId);
+    if (!state)
+      return;
+    sessions.delete(sessionId);
+    await closeSessionState(state);
+  }
+  async function handleStateful(request) {
+    const requestedSessionId = request.headers.get("mcp-session-id");
+    let state;
+    let createdState = false;
+    if (requestedSessionId) {
+      const existing = sessions.get(requestedSessionId);
+      if (!existing) {
+        return createJsonRpcErrorResponse(404, -32001, "Session not found");
+      }
+      state = existing;
+    } else {
+      state = await createSessionState({
+        logger,
+        path,
+        serverName,
+        ops,
+        resources,
+        prompts,
+        presentations,
+        stateful: true
+      });
+      createdState = true;
+    }
+    try {
+      const response = await state.transport.handleRequest(request);
+      const activeSessionId = state.transport.sessionId;
+      if (activeSessionId && !sessions.has(activeSessionId)) {
+        sessions.set(activeSessionId, state);
+      }
+      if (request.method === "DELETE" && activeSessionId) {
+        await closeSession(activeSessionId);
+      } else if (!activeSessionId && createdState) {
+        await closeSessionState(state);
+      }
+      return response;
+    } catch (error) {
+      if (createdState) {
+        await closeSessionState(state);
+      }
+      throw error;
+    }
+  }
+  return new Elysia({ name: `mcp-${serverName}` }).all(path, async ({ request }) => {
+    try {
+      if (validateAuth) {
+        const authResult = await validateAuth(request);
+        if (!authResult.valid) {
+          return createJsonRpcErrorResponse(401, -32002, "Authentication failed", authResult.reason);
+        }
+      }
+      if (isStateful) {
+        return await handleStateful(request);
+      }
+      return await handleStateless(request);
+    } catch (error) {
+      logger.error("Error handling MCP request", {
+        path,
+        method: request.method,
+        error: toErrorMessage(error)
+      });
+      return createJsonRpcErrorResponse(500, -32000, "Internal error");
+    }
+  });
+}
+
+// src/infrastructure/elysia/logger.ts
+import { Logger, LogLevel } from "@contractspec/lib.logger";
+var createAppLogger = () => new Logger({
+  level: LogLevel.DEBUG,
+  environment: "development",
+  enableTracing: true,
+  enableTiming: true,
+  enableContext: true,
+  enableColors: true
+});
+var appLogger = createAppLogger();
+var dbLogger = new Logger({
+  level: LogLevel.DEBUG,
+  environment: "development",
+  enableTracing: true,
+  enableTiming: true,
+  enableContext: true,
+  enableColors: true
+});
+var authLogger = new Logger({
+  level: LogLevel.INFO,
+  environment: "development",
+  enableTracing: true,
+  enableTiming: true,
+  enableContext: true,
+  enableColors: true
+});
+// src/application/mcp/providerRankingMcp.ts
+import {
+  definePrompt,
+  defineResourceTemplate,
+  installOp,
+  OperationSpecRegistry,
+  PromptRegistry,
+  ResourceRegistry
+} from "@contractspec/lib.contracts-spec";
+import {
+  BenchmarkIngestCommand,
+  BenchmarkRunCustomCommand,
+  RankingRefreshCommand
+} from "@contractspec/lib.contracts-spec/provider-ranking";
+import z from "zod";
+import { InMemoryProviderRankingStore } from "@contractspec/lib.provider-ranking/in-memory-store";
+import { createDefaultIngesterRegistry } from "@contractspec/lib.provider-ranking/ingesters";
+import { computeModelRankings } from "@contractspec/lib.provider-ranking/scoring";
+import { normalizeBenchmarkResults } from "@contractspec/lib.provider-ranking/scoring";
+var TransportFilterSchema = z.enum(["rest", "mcp", "webhook", "sdk"]).optional();
+var AuthFilterSchema = z.enum([
+  "api-key",
+  "oauth2",
+  "bearer",
+  "header",
+  "basic",
+  "webhook-signing",
+  "service-account"
+]).optional();
+var RANKING_TAGS = ["ranking", "mcp", "ai"];
+var RANKING_OWNERS = ["platform.ai"];
+var sharedStore = null;
+function getStore() {
+  if (!sharedStore) {
+    sharedStore = new InMemoryProviderRankingStore;
+  }
+  return sharedStore;
+}
+function buildRankingResources() {
+  const resources = new ResourceRegistry;
+  resources.register(defineResourceTemplate({
+    meta: {
+      uriTemplate: "ranking://leaderboard",
+      title: "AI Model Leaderboard",
+      description: "Current ranked list of AI models by composite score. Supports optional transport and authMethod query filters.",
+      mimeType: "application/json",
+      tags: RANKING_TAGS
+    },
+    input: z.object({
+      transport: TransportFilterSchema,
+      authMethod: AuthFilterSchema
+    }),
+    resolve: async ({ transport, authMethod }) => {
+      const store = getStore();
+      const result = await store.listModelRankings({
+        limit: 100,
+        requiredTransport: transport,
+        requiredAuthMethod: authMethod
+      });
+      return {
+        uri: "ranking://leaderboard",
+        mimeType: "application/json",
+        data: JSON.stringify(result, null, 2)
+      };
+    }
+  }));
+  resources.register(defineResourceTemplate({
+    meta: {
+      uriTemplate: "ranking://leaderboard/{dimension}",
+      title: "AI Model Leaderboard by Dimension",
+      description: "Ranked list of AI models filtered by a specific dimension. Supports optional transport and authMethod query filters.",
+      mimeType: "application/json",
+      tags: RANKING_TAGS
+    },
+    input: z.object({
+      dimension: z.string(),
+      transport: TransportFilterSchema,
+      authMethod: AuthFilterSchema
+    }),
+    resolve: async ({ dimension, transport, authMethod }) => {
+      const store = getStore();
+      const result = await store.listModelRankings({
+        dimension,
+        limit: 100,
+        requiredTransport: transport,
+        requiredAuthMethod: authMethod
+      });
+      return {
+        uri: `ranking://leaderboard/${encodeURIComponent(dimension)}`,
+        mimeType: "application/json",
+        data: JSON.stringify(result, null, 2)
+      };
+    }
+  }));
+  resources.register(defineResourceTemplate({
+    meta: {
+      uriTemplate: "ranking://model/{modelId}",
+      title: "AI Model Profile",
+      description: "Detailed profile for a specific AI model including scores and benchmarks.",
+      mimeType: "application/json",
+      tags: RANKING_TAGS
+    },
+    input: z.object({ modelId: z.string() }),
+    resolve: async ({ modelId }) => {
+      const store = getStore();
+      const profile = await store.getModelProfile(modelId);
+      if (!profile) {
+        return {
+          uri: `ranking://model/${encodeURIComponent(modelId)}`,
+          mimeType: "application/json",
+          data: JSON.stringify({ error: "not_found", modelId })
+        };
+      }
+      return {
+        uri: `ranking://model/${encodeURIComponent(modelId)}`,
+        mimeType: "application/json",
+        data: JSON.stringify(profile, null, 2)
+      };
+    }
+  }));
+  resources.register(defineResourceTemplate({
+    meta: {
+      uriTemplate: "ranking://results",
+      title: "Benchmark Results",
+      description: "List of raw benchmark results from all ingested sources.",
+      mimeType: "application/json",
+      tags: RANKING_TAGS
+    },
+    input: z.object({}),
+    resolve: async () => {
+      const store = getStore();
+      const result = await store.listBenchmarkResults({ limit: 200 });
+      return {
+        uri: "ranking://results",
+        mimeType: "application/json",
+        data: JSON.stringify(result, null, 2)
+      };
+    }
+  }));
+  return resources;
+}
+function buildRankingPrompts() {
+  const prompts = new PromptRegistry;
+  prompts.register(definePrompt({
+    meta: {
+      key: "ranking.advisor",
+      version: "1.0.0",
+      title: "AI Model Advisor",
+      description: "Which AI model is best for a given task? Uses the leaderboard to recommend.",
+      tags: RANKING_TAGS,
+      stability: "beta",
+      owners: RANKING_OWNERS
+    },
+    args: [
+      {
+        name: "task",
+        description: "The task or use case to recommend a model for.",
+        required: true,
+        schema: z.string()
+      },
+      {
+        name: "priority",
+        description: "Priority dimension (coding, reasoning, cost, latency, etc.).",
+        required: false,
+        schema: z.string().optional()
+      },
+      {
+        name: "transport",
+        description: "Required transport type (rest, mcp, webhook, sdk).",
+        required: false,
+        schema: TransportFilterSchema
+      },
+      {
+        name: "authMethod",
+        description: "Required auth method (api-key, oauth2, bearer, etc.).",
+        required: false,
+        schema: AuthFilterSchema
+      }
+    ],
+    input: z.object({
+      task: z.string(),
+      priority: z.string().optional(),
+      transport: TransportFilterSchema,
+      authMethod: AuthFilterSchema
+    }),
+    render: async ({ task, priority, transport, authMethod }) => {
+      const constraints = [];
+      if (priority)
+        constraints.push(`Prioritize: ${priority}.`);
+      if (transport)
+        constraints.push(`Required transport: ${transport}.`);
+      if (authMethod)
+        constraints.push(`Required auth: ${authMethod}.`);
+      return [
+        {
+          type: "text",
+          text: `Recommend the best AI model for: "${task}".${constraints.length ? ` ${constraints.join(" ")}` : ""} Use the leaderboard data to justify your recommendation.`
+        },
+        {
+          type: "resource",
+          uri: priority ? `ranking://leaderboard/${priority}` : "ranking://leaderboard",
+          title: "Leaderboard"
+        }
+      ];
+    }
+  }));
+  return prompts;
+}
+function buildRankingOps() {
+  const registry = new OperationSpecRegistry;
+  const ingesterRegistry = createDefaultIngesterRegistry();
+  installOp(registry, BenchmarkIngestCommand, async (args) => {
+    const store = getStore();
+    const source = args.source;
+    const ingester = ingesterRegistry.get(source);
+    if (!ingester) {
+      throw new Error(`No ingester registered for source: ${source}`);
+    }
+    const rawResults = await ingester.ingest({
+      sourceUrl: args.sourceUrl,
+      dimensions: args.dimensions
+    });
+    const normalized = normalizeBenchmarkResults(rawResults);
+    for (const result of normalized) {
+      await store.upsertBenchmarkResult(result);
+    }
+    return {
+      ingestionId: `ingest-${source}-${Date.now()}`,
+      source,
+      resultsCount: normalized.length,
+      status: "completed",
+      ingestedAt: new Date
+    };
+  });
+  installOp(registry, BenchmarkRunCustomCommand, async (args) => {
+    return {
+      runId: `custom-${Date.now()}`,
+      evalSuiteKey: args.evalSuiteKey,
+      modelId: args.modelId,
+      status: "started",
+      startedAt: new Date
+    };
+  });
+  installOp(registry, RankingRefreshCommand, async (args) => {
+    const store = getStore();
+    const allResults = [];
+    let offset = 0;
+    const pageSize = 500;
+    while (true) {
+      const page = await store.listBenchmarkResults({
+        limit: pageSize,
+        offset
+      });
+      allResults.push(...page.results);
+      if (allResults.length >= page.total || page.results.length < pageSize)
+        break;
+      offset += pageSize;
+    }
+    const existingRankings = new Map((await store.listModelRankings({ limit: 1e4 })).rankings.map((r) => [
+      r.modelId,
+      r
+    ]));
+    const weightOverrides = args.weightOverrides ? Array.isArray(args.weightOverrides) ? args.weightOverrides : [args.weightOverrides] : undefined;
+    const newRankings = computeModelRankings(allResults, weightOverrides ? {
+      weightOverrides
+    } : undefined, existingRankings);
+    for (const ranking of newRankings) {
+      await store.upsertModelRanking(ranking);
+    }
+    return {
+      modelsRanked: newRankings.length,
+      updatedAt: new Date,
+      status: "completed"
+    };
+  });
+  return registry;
+}
+function createProviderRankingMcpHandler(path = "/api/mcp/ranking") {
+  return createMcpElysiaHandler({
+    logger: appLogger,
+    path,
+    serverName: "contractspec-ranking-mcp",
+    ops: buildRankingOps(),
+    resources: buildRankingResources(),
+    prompts: buildRankingPrompts()
+  });
+}
+function setProviderRankingStore(store) {
+  sharedStore = store;
+}
+export {
+  setProviderRankingStore,
+  createProviderRankingMcpHandler
+};

package/dist/node/components/docs/DocsIndexPage.js

@@ -207,7 +207,7 @@ bun contractspec build src/contracts/mySpec.ts`
               },
               {
                 title: "Ecosystem",
-                description: "Plugin API, templates, and integrations",
+                description: "Cursor marketplace plugins, templates, manifest, and integrations",
                 href: "/docs/ecosystem/plugins"
               },
               {

package/dist/node/components/docs/architecture/ArchitectureControlPlanePage.js

@@ -0,0 +1,203 @@
+// src/components/docs/architecture/ArchitectureControlPlanePage.tsx
+import { CodeBlock } from "@contractspec/lib.design-system";
+import Link from "@contractspec/lib.ui-link";
+import { ChevronRight } from "lucide-react";
+import { jsxDEV } from "react/jsx-dev-runtime";
+function ArchitectureControlPlanePage() {
+  return /* @__PURE__ */ jsxDEV("div", {
+    className: "space-y-8",
+    children: [
+      /* @__PURE__ */ jsxDEV("div", {
+        className: "space-y-4",
+        children: [
+          /* @__PURE__ */ jsxDEV("h1", {
+            className: "text-4xl font-bold",
+            children: "Control Plane Runtime"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV("p", {
+            className: "text-muted-foreground",
+            children: "The control plane is the governance layer for agentic execution. It turns incoming intent into deterministic plans, enforces risk policy before side effects, and records replayable traces for audits."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV("div", {
+        className: "space-y-4",
+        children: [
+          /* @__PURE__ */ jsxDEV("h2", {
+            className: "text-2xl font-bold",
+            children: "Canonical execution loop"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV("ol", {
+            className: "text-muted-foreground list-inside list-decimal space-y-2",
+            children: [
+              /* @__PURE__ */ jsxDEV("li", {
+                children: "Accept intent and create execution identity + trace context."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV("li", {
+                children: "Compile intent into a typed, deterministic plan DAG."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV("li", {
+                children: "Verify plan against policy and risk rules."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV("li", {
+                children: "Route into autonomous or assist mode based on verdict."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV("li", {
+                children: "Execute steps with idempotent keys and explicit stage events."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV("li", {
+                children: "Persist outcomes for replay, audits, and operator visibility."
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV("div", {
+        className: "space-y-4",
+        children: [
+          /* @__PURE__ */ jsxDEV("h2", {
+            className: "text-2xl font-bold",
+            children: "Contract surfaces (v1 baseline)"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV("p", {
+            className: "text-muted-foreground",
+            children: [
+              "The runtime is contract-first. Commands, queries, events, and capabilities are explicit and versioned under",
+              /* @__PURE__ */ jsxDEV("code", {
+                children: " @contractspec/lib.contracts-spec"
+              }, undefined, false, undefined, this),
+              "."
+            ]
+          }, undefined, true, undefined, this),
+          /* @__PURE__ */ jsxDEV(CodeBlock, {
+            language: "text",
+            code: `Commands
+- controlPlane.intent.submit
+- controlPlane.plan.compile
+- controlPlane.plan.verify
+- controlPlane.execution.start
+- controlPlane.execution.approve
+- controlPlane.execution.reject
+- controlPlane.execution.cancel
+- controlPlane.skill.install
+- controlPlane.skill.disable
+
+Queries
+- controlPlane.execution.get
+- controlPlane.execution.list
+- controlPlane.trace.get
+- controlPlane.policy.explain
+- controlPlane.skill.list
+- controlPlane.skill.verify
+
+Events
+- controlPlane.intent.received
+- controlPlane.plan.compiled
+- controlPlane.plan.rejected
+- controlPlane.execution.step.started
+- controlPlane.execution.step.blocked
+- controlPlane.execution.step.completed
+- controlPlane.execution.completed
+- controlPlane.execution.failed
+- controlPlane.skill.installed
+- controlPlane.skill.rejected
+
+Capabilities
+- control-plane.core
+- control-plane.approval
+- control-plane.audit
+- control-plane.skill-registry
+- control-plane.channel-runtime`
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV("div", {
+        className: "space-y-4",
+        children: [
+          /* @__PURE__ */ jsxDEV("h2", {
+            className: "text-2xl font-bold",
+            children: "Policy and safety posture"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV("ul", {
+            className: "text-muted-foreground list-inside list-disc space-y-2",
+            children: [
+              /* @__PURE__ */ jsxDEV("li", {
+                children: "No side-effect action executes unless it comes from a compiled plan."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV("li", {
+                children: "High-risk actions are blocked from autonomous mode in v1."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV("li", {
+                children: "Approval commands provide explicit human-in-the-loop transitions."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV("li", {
+                children: "Skill installation is modeled as governance-controlled operations."
+              }, undefined, false, undefined, this),
+              /* @__PURE__ */ jsxDEV("li", {
+                children: "Trace queries expose policy rationale and step outcomes for replay."
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV("div", {
+        className: "space-y-4",
+        children: [
+          /* @__PURE__ */ jsxDEV("h2", {
+            className: "text-2xl font-bold",
+            children: "Implementation map"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV(CodeBlock, {
+            language: "text",
+            code: `packages/libs/contracts-spec/src/control-plane/
+  commands/
+  queries/
+  events/
+  capabilities/
+  contracts.ts
+  contracts.test.ts
+
+packages/apps/web-landing/src/app/docs/architecture/control-plane/page.tsx
+implementation_plan_controle_plane.md`
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV("div", {
+        className: "space-y-4",
+        children: [
+          /* @__PURE__ */ jsxDEV("h2", {
+            className: "text-2xl font-bold",
+            children: "What comes next"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV("p", {
+            className: "text-muted-foreground",
+            children: "WS1 delivers the contract fabric. Next increments add planner/executor split, policy escalation, capability-bound authorization, signed skill compatibility checks, and full replay tooling."
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV("div", {
+        className: "flex items-center gap-4 pt-4",
+        children: [
+          /* @__PURE__ */ jsxDEV(Link, {
+            href: "/docs/architecture/integration-binding",
+            className: "btn-ghost",
+            children: "Previous: Integration Binding"
+          }, undefined, false, undefined, this),
+          /* @__PURE__ */ jsxDEV(Link, {
+            href: "/docs/safety/auditing",
+            className: "btn-primary",
+            children: [
+              "Audit Logs ",
+              /* @__PURE__ */ jsxDEV(ChevronRight, {
+                size: 16
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this)
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+export {
+  ArchitectureControlPlanePage
+};