release: SDK 0.6.1 — sync to engine v0.6.1 (stored-queries support)

.github/workflows/e2e.yml

@@ -81,11 +81,14 @@ jobs:
                   - branch_merge
           YAML
           cat > /tmp/og/omnigraph.yaml <<'YAML'
-          policy:
-            file: /tmp/og/policy.yaml
           graphs:
             e2e:
               uri: /tmp/og/repo.omni
+              # Per-graph policy: server 0.6.1+ rejects a top-level `policy.file`
+              # alongside a named graph (it would be silently ignored), so the
+              # policy must live under the graph it applies to.
+              policy:
+                file: /tmp/og/policy.yaml
           cli:
             graph: e2e
             branch: main

package.json

@@ -11,7 +11,7 @@
   },
   "packageManager": "pnpm@9.15.0",
   "omnigraph": {
-    "serverVersion": "0.6.0"
+    "serverVersion": "0.6.1"
   },
   "scripts": {
     "sync-spec": "tsx scripts/sync-spec.ts",

packages/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modernrelay/omnigraph-mcp",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "MCP server exposing an Omnigraph database to LLM clients (Tools + Resources, stdio transport).",
   "license": "MIT",
   "repository": {

packages/mcp/src/version.gen.ts

@@ -4,4 +4,4 @@
 /**
  * The MCP server package version reported in the MCP initialize response.
  */
-export const MCP_PACKAGE_VERSION = "0.6.0";
+export const MCP_PACKAGE_VERSION = "0.6.1";

packages/mcp/test/server.test.ts

@@ -83,7 +83,7 @@ describe('omnigraph-mcp server', () => {
     const { client } = await setup();
     const info = client.getServerVersion();
     expect(info?.name).toBe('omnigraph-mcp');
-    expect(info?.version).toBe('0.6.0');
+    expect(info?.version).toBe('0.6.1');
   });
 
   it('lists every expected tool', async () => {
@@ -133,7 +133,7 @@ describe('omnigraph-mcp server', () => {
     const parsed = JSON.parse(block.text);
     expect(parsed.status).toBe('ok');
     expect(parsed.version).toBe('0.3.0');
-    expect(parsed.sdkServerVersion).toBe('0.6.0');
+    expect(parsed.sdkServerVersion).toBe('0.6.1');
   });
 
   it('calls the read tool and preserves opaque param keys', async () => {

packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modernrelay/omnigraph",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "TypeScript SDK for the Omnigraph HTTP API.",
   "license": "MIT",
   "repository": {

packages/sdk/src/client.ts

@@ -5,6 +5,7 @@ import { BranchesResource } from './resources/branches';
 import type { CallOptions } from './internals';
 import { CommitsResource } from './resources/commits';
 import { GraphsResource } from './resources/graphs';
+import { QueriesResource } from './resources/queries';
 import { SchemaResource } from './resources/schema';
 import type {
   Change,
@@ -85,6 +86,7 @@ export default class Omnigraph {
   readonly branches: BranchesResource;
   readonly commits: CommitsResource;
   readonly graphs: GraphsResource;
+  readonly queries: QueriesResource;
   readonly schema: SchemaResource;
 
   private readonly t: Transport;
@@ -96,6 +98,7 @@ export default class Omnigraph {
     this.branches = new BranchesResource(this.t);
     this.commits = new CommitsResource(this.t);
     this.graphs = new GraphsResource(this.t);
+    this.queries = new QueriesResource(this.t);
     this.schema = new SchemaResource(this.t);
   }
 

packages/sdk/src/generated/index.ts

@@ -69,6 +69,13 @@ export {
   type IngestResponse,
   type IngestResponses,
   type IngestTableOutput,
+  type InvokeQueryData,
+  type InvokeQueryError,
+  type InvokeQueryErrors,
+  type InvokeQueryResponse,
+  type InvokeQueryResponses,
+  type InvokeStoredQueryRequest,
+  type InvokeStoredQueryResponse,
   type ListBranchesData,
   type ListBranchesError,
   type ListBranchesErrors,
@@ -84,6 +91,11 @@ export {
   type ListGraphsErrors,
   type ListGraphsResponse,
   type ListGraphsResponses,
+  type ListQueriesData,
+  type ListQueriesError,
+  type ListQueriesErrors,
+  type ListQueriesResponse,
+  type ListQueriesResponses,
   LoadMode,
   type ManifestConflictOutput,
   type MergeBranchesData,
@@ -98,6 +110,10 @@ export {
   type MutateErrors,
   type MutateResponse,
   type MutateResponses,
+  type ParamDescriptor,
+  ParamKind,
+  type QueriesCatalogOutput,
+  type QueryCatalogEntry,
   type QueryData,
   type QueryError,
   type QueryErrors,

packages/sdk/src/generated/types.gen.ts

@@ -201,6 +201,37 @@ export type IngestTableOutput = {
   table_key: string;
 };
 
+/**
+ * Body for `POST /queries/{name}` — invokes the server-side stored query
+ * named in the path. The query source and name come from the registry,
+ * never the body; only the runtime inputs are supplied here.
+ */
+export type InvokeStoredQueryRequest = {
+  /**
+   * Branch to run against. Defaults to `main`; for a stored mutation the
+   * write targets this branch.
+   */
+  branch?: string | null;
+  /**
+   * JSON object whose keys match the stored query's declared parameters.
+   */
+  params?: unknown;
+  /**
+   * Snapshot id to read from (read queries only — rejected for a stored
+   * mutation). Mutually exclusive with `branch`.
+   */
+  snapshot?: string | null;
+};
+
+/**
+ * Response for `POST /queries/{name}`: the read envelope for a stored
+ * read, or the mutation envelope for a stored mutation. Serialized
+ * **untagged**, so the wire shape is exactly [`ReadOutput`] or
+ * [`ChangeOutput`] — classification follows the stored query, not a
+ * wrapper field.
+ */
+export type InvokeStoredQueryResponse = ReadOutput | ChangeOutput;
+
 /**
  * Shadow enum for documenting [`LoadMode`] in the OpenAPI schema.
  */
@@ -247,6 +278,83 @@ export type MergeConflictOutput = {
   table_key: string;
 };
 
+/**
+ * One declared parameter of a stored query, projected for the catalog.
+ */
+export type ParamDescriptor = {
+  item_kind?: null | ParamKind;
+  kind: ParamKind;
+  name: string;
+  /**
+   * `false` → the caller must supply it; `true` → optional.
+   */
+  nullable: boolean;
+  /**
+   * Dimension when `kind == vector`.
+   */
+  vector_dim?: number | null;
+};
+
+/**
+ * The kind of a stored-query parameter, decomposed so a client (e.g. an
+ * MCP server) can build a typed input schema with a closed `match` and
+ * never re-parse omnigraph's type spelling. `bigint`/`date`/`datetime`/
+ * `blob` are carried as JSON strings on the wire: a 64-bit integer past
+ * 2^53 loses precision as a JSON number, and Date/DateTime are ISO
+ * strings, Blob a blob-URI string.
+ */
+export const ParamKind = {
+  STRING: "string",
+  BOOL: "bool",
+  INT: "int",
+  BIGINT: "bigint",
+  FLOAT: "float",
+  DATE: "date",
+  DATETIME: "datetime",
+  BLOB: "blob",
+  VECTOR: "vector",
+  LIST: "list",
+} as const;
+
+/**
+ * The kind of a stored-query parameter, decomposed so a client (e.g. an
+ * MCP server) can build a typed input schema with a closed `match` and
+ * never re-parse omnigraph's type spelling. `bigint`/`date`/`datetime`/
+ * `blob` are carried as JSON strings on the wire: a 64-bit integer past
+ * 2^53 loses precision as a JSON number, and Date/DateTime are ISO
+ * strings, Blob a blob-URI string.
+ */
+export type ParamKind = (typeof ParamKind)[keyof typeof ParamKind];
+
+/**
+ * Response for `GET /queries`: the `mcp.expose` subset of a graph's
+ * stored-query registry, each with typed parameters.
+ */
+export type QueriesCatalogOutput = {
+  queries: Array<QueryCatalogEntry>;
+};
+
+/**
+ * One entry in the stored-query catalog (`GET /queries`).
+ */
+export type QueryCatalogEntry = {
+  description?: string | null;
+  instruction?: string | null;
+  /**
+   * `true` for a stored mutation → an MCP read-only hint of `false`.
+   */
+  mutation: boolean;
+  /**
+   * Registry key / invoke path segment (`POST /queries/{name}`).
+   */
+  name: string;
+  params: Array<ParamDescriptor>;
+  /**
+   * MCP tool id (the `tool_name` override, else `name`).
+   */
+  tool_name: string;
+};
+
 /**
  * Inline read-query request for `POST /query`.
  *
@@ -789,6 +897,91 @@ export type MutateResponses = {
 
 export type MutateResponse = MutateResponses[keyof MutateResponses];
 
+export type ListQueriesData = {
+  body?: never;
+  path?: never;
+  query?: never;
+  url: "/queries";
+};
+
+export type ListQueriesErrors = {
+  /**
+   * Unauthorized
+   */
+  401: ErrorOutput;
+  /**
+   * Forbidden
+   */
+  403: ErrorOutput;
+};
+
+export type ListQueriesError = ListQueriesErrors[keyof ListQueriesErrors];
+
+export type ListQueriesResponses = {
+  /**
+   * Stored-query catalog (the mcp.expose subset, with typed params)
+   */
+  200: QueriesCatalogOutput;
+};
+
+export type ListQueriesResponse =
+  ListQueriesResponses[keyof ListQueriesResponses];
+
+export type InvokeQueryData = {
+  body?: null | InvokeStoredQueryRequest;
+  path: {
+    /**
+     * Stored query name (the registry key)
+     */
+    name: string;
+  };
+  query?: never;
+  url: "/queries/{name}";
+};
+
+export type InvokeQueryErrors = {
+  /**
+   * Bad request (param type error; snapshot on a stored mutation)
+   */
+  400: ErrorOutput;
+  /**
+   * Unauthorized
+   */
+  401: ErrorOutput;
+  /**
+   * Forbidden (the inner `change` gate for a stored mutation)
+   */
+  403: ErrorOutput;
+  /**
+   * Unknown stored query, or `invoke_query` denied — indistinguishable to a caller without the grant
+   */
+  404: ErrorOutput;
+  /**
+   * Merge conflict
+   */
+  409: ErrorOutput;
+  /**
+   * Per-actor admission cap exceeded; honor `Retry-After` header
+   */
+  429: ErrorOutput;
+  /**
+   * Policy evaluation error (a denial is reported as 404, not 500)
+   */
+  500: ErrorOutput;
+};
+
+export type InvokeQueryError = InvokeQueryErrors[keyof InvokeQueryErrors];
+
+export type InvokeQueryResponses = {
+  /**
+   * Read envelope (ReadOutput) or mutation envelope (ChangeOutput), serialized untagged
+   */
+  200: InvokeStoredQueryResponse;
+};
+
+export type InvokeQueryResponse =
+  InvokeQueryResponses[keyof InvokeQueryResponses];
+
 export type QueryData = {
   body: QueryRequest;
   path?: never;

packages/sdk/src/index.ts

@@ -60,6 +60,12 @@ export type {
   ReadTarget,
   Snapshot,
   SnapshotTable,
+  // Stored queries
+  Queries,
+  QueryCatalogEntry,
+  ParamDescriptor,
+  InvokeQuery,
+  InvokeQueryInput,
   // Conflict / errors / shared
   MergeConflict,
   ManifestConflict,
@@ -76,4 +82,5 @@ export {
   ErrorCode,
   LoadMode,
   MergeConflictKindOutput,
+  ParamKind,
 } from './types';