@treeseed/sdk 0.13.0-rc.18 → 0.13.0-rc.19

package/dist/operator-contracts/control-plane-operation.js

@@ -52,6 +52,9 @@ function validateControlPlaneCatalog(catalog) {
     }
     for (const duplicate of duplicates(operation.surfaces)) diagnostics.push({ code: "surface_duplicate", path: `${path}.surfaces`, message: `Duplicate operation surface ${duplicate}.` });
     for (const duplicate of duplicates(operation.oauthScopes)) diagnostics.push({ code: "oauth_scope_duplicate", path: `${path}.oauthScopes`, message: `Duplicate OAuth scope ${duplicate}.` });
+    if (operation.upstream && (!operation.upstream.operationId || !/^sha256:[0-9a-f]{64}$/u.test(operation.upstream.contractDigest))) {
+      diagnostics.push({ code: "upstream_binding_invalid", path: `${path}.upstream`, message: "Upstream bindings require an operation ID and exact SHA-256 contract digest." });
+    }
     const elevatedRisk = operation.riskClass !== "ordinary";
     if (elevatedRisk !== (operation.confirmation === "input_required")) {
       diagnostics.push({ code: "confirmation_policy_invalid", path: `${path}.confirmation`, message: "Elevated-risk operations require input_required; ordinary operations must not." });

package/dist/operator-contracts/control-plane-operations.d.ts

@@ -598,45 +598,286 @@ export declare const CONTROL_PLANE_OPERATIONS: {
         readonly bindLibrary: ControlPlaneOperationBinding<{
             projectId: string;
         }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
-        readonly createRepository: ControlPlaneOperationBinding<{
-            projectId: string;
-        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
-        readonly createWorkspace: ControlPlaneOperationBinding<{
-            projectId: string;
-            repoId: string;
-        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
-        readonly readWorkspaceFile: ControlPlaneOperationBinding<{
-            projectId: string;
-            workspaceId: string;
-        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
-        readonly applyChangeset: ControlPlaneOperationBinding<{
-            projectId: string;
-            workspaceId: string;
-        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
-        readonly searchWorkspace: ControlPlaneOperationBinding<{
-            projectId: string;
-            workspaceId: string;
-        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
-        readonly commitWorkspace: ControlPlaneOperationBinding<{
-            projectId: string;
-            workspaceId: string;
-        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
-        readonly closeWorkspace: ControlPlaneOperationBinding<{
-            projectId: string;
-            workspaceId: string;
-        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
-        readonly readRepositoryFiles: ControlPlaneOperationBinding<{
-            projectId: string;
-            repoId: string;
-        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
-        readonly listRepositoryPaths: ControlPlaneOperationBinding<{
-            projectId: string;
-            repoId: string;
-        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
-        readonly buildRepositoryContext: ControlPlaneOperationBinding<{
-            projectId: string;
-            repoId: string;
-        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        readonly serviceContract: ControlPlaneOperationBinding<{
+            projectId: string;
+        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        readonly health: ControlPlaneOperationBinding<{
+            projectId: string;
+        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        readonly readiness: ControlPlaneOperationBinding<{
+            projectId: string;
+        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        readonly version: ControlPlaneOperationBinding<{
+            projectId: string;
+        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        readonly capabilities: ControlPlaneOperationBinding<{
+            projectId: string;
+        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        readonly effectiveScope: ControlPlaneOperationBinding<{
+            projectId: string;
+        }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        readonly repositories: {
+            readonly list: ControlPlaneOperationBinding<{
+                projectId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly create: ControlPlaneOperationBinding<{
+                projectId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly show: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly status: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly refs: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly sync: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly push: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly promoteRef: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly retireRef: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly readFiles: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly listPaths: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly searchFiles: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly query: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        };
+        readonly workspaces: {
+            readonly list: ControlPlaneOperationBinding<{
+                projectId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly create: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly show: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly status: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly diff: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly tree: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly close: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly abandon: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        };
+        readonly files: {
+            readonly read: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly write: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly writeBatch: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly patch: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly remove: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly search: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly applyChangeset: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly commit: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        };
+        readonly blobs: {
+            readonly read: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly write: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly remove: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly download: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly upload: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly createUpload: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly uploadPart: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+                uploadId: string;
+                partNumber: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly completeUpload: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+                uploadId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly abortUpload: ControlPlaneOperationBinding<{
+                projectId: string;
+                workspaceId: string;
+                uploadId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        };
+        readonly graph: {
+            readonly refresh: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly refreshJob: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+                jobId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly query: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly node: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+                nodeId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly related: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly subgraph: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly searchFiles: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly searchSections: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly searchEntities: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        };
+        readonly context: {
+            readonly build: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly parse: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        };
+        readonly federated: {
+            readonly search: ControlPlaneOperationBinding<{
+                projectId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly query: ControlPlaneOperationBinding<{
+                projectId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly context: ControlPlaneOperationBinding<{
+                projectId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly graph: ControlPlaneOperationBinding<{
+                projectId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        };
+        readonly snapshots: {
+            readonly build: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly show: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+                snapshotId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        };
+        readonly artifacts: {
+            readonly export: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly list: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly show: ControlPlaneOperationBinding<{
+                projectId: string;
+                artifactId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+            readonly remove: ControlPlaneOperationBinding<{
+                projectId: string;
+                artifactId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        };
+        readonly searchIndex: {
+            readonly status: ControlPlaneOperationBinding<{
+                projectId: string;
+                repoId: string;
+            }, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+        };
     };
     readonly providers: {
         readonly register: ControlPlaneOperationBinding<{}, {}, Record<string, unknown> | undefined, Record<string, unknown>>;

package/dist/operator-contracts/control-plane-operations.js

@@ -1,34 +1,9 @@
 import { z } from "zod";
-import {
-  CONTROL_PLANE_OPERATION_SCHEMA_VERSION
-} from "./control-plane-operation.js";
+import { defineOperation as define, defineTreeDxProxyOperation as treedxProxy } from "./operation-builder.js";
 const empty = z.object({}).strict();
 const none = z.undefined();
 const record = z.record(z.unknown());
 const payload = record;
-function define(definition, schema) {
-  const { parameters, redactedPaths = [], idempotencyRequired, concurrencyRequired, ...descriptor } = definition;
-  const mutation = definition.kind === "mutation";
-  return {
-    descriptor: {
-      ...descriptor,
-      authentication: definition.authentication ?? (definition.oauthScopes.length ? "oauth" : "anonymous"),
-      schemaVersion: CONTROL_PLANE_OPERATION_SCHEMA_VERSION,
-      schemas: {
-        input: `treeseed.${definition.operationId}.input/v1`,
-        output: `treeseed.${definition.operationId}.output/v1`,
-        errors: "treeseed.problem/v1",
-        ...parameters ? { parameters } : {}
-      },
-      idempotency: { required: idempotencyRequired ?? mutation, header: "Idempotency-Key" },
-      concurrency: { required: concurrencyRequired ?? false, readHeader: "ETag", writeHeader: "If-Match" },
-      audited: definition.surfaces.some((surface) => surface !== "internal"),
-      receipt: mutation,
-      redactedPaths
-    },
-    schema
-  };
-}
 function read(operationId, path, capability, surfaces = ["rest"]) {
   return define({
     operationId,
@@ -353,18 +328,94 @@ const CONTROL_PLANE_OPERATIONS = {
     actionResult: resource("realtime.actions.result", "POST", "/v1/client-sessions/{sessionId}/actions/{actionId}/result", { sessionId: z.string().min(1), actionId: z.string().min(1) }, { capability: "realtime.write" })
   },
   treedx: {
-    library: resource("treedx.library.show", "GET", "/v1/projects/{projectId}/treedx-library", { projectId: z.string().min(1) }, { capability: "treedx.read" }),
-    bindLibrary: resource("treedx.library.bind", "POST", "/v1/projects/{projectId}/treedx-library", { projectId: z.string().min(1) }, { capability: "treedx.write" }),
-    createRepository: resource("treedx.repositories.create", "POST", "/v1/dx/projects/{projectId}/repos", { projectId: z.string().min(1) }, { capability: "treedx.write", authentication: "oauth_or_provider" }),
-    createWorkspace: resource("treedx.workspaces.create", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/workspaces", { projectId: z.string().min(1), repoId: z.string().min(1) }, { capability: "treedx.write", authentication: "oauth_or_provider" }),
-    readWorkspaceFile: resource("treedx.workspaces.files.read", "GET", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/files", { projectId: z.string().min(1), workspaceId: z.string().min(1) }, { capability: "treedx.read", authentication: "oauth_or_provider" }),
-    applyChangeset: resource("treedx.workspaces.changesets.apply", "POST", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/changesets", { projectId: z.string().min(1), workspaceId: z.string().min(1) }, { capability: "treedx.write", authentication: "oauth_or_provider" }),
-    searchWorkspace: resource("treedx.workspaces.search", "POST", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/search", { projectId: z.string().min(1), workspaceId: z.string().min(1) }, { capability: "treedx.read", authentication: "oauth_or_provider", scopes: ["treeseed:read"] }),
-    commitWorkspace: resource("treedx.workspaces.commit", "POST", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/commit", { projectId: z.string().min(1), workspaceId: z.string().min(1) }, { capability: "treedx.write", authentication: "oauth_or_provider" }),
-    closeWorkspace: resource("treedx.workspaces.close", "POST", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/close", { projectId: z.string().min(1), workspaceId: z.string().min(1) }, { capability: "treedx.write", authentication: "oauth_or_provider" }),
-    readRepositoryFiles: resource("treedx.repositories.files.read", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/files/read", { projectId: z.string().min(1), repoId: z.string().min(1) }, { capability: "treedx.read", authentication: "oauth_or_provider", scopes: ["treeseed:read"] }),
-    listRepositoryPaths: resource("treedx.repositories.paths.list", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/paths/list", { projectId: z.string().min(1), repoId: z.string().min(1) }, { capability: "treedx.read", authentication: "oauth_or_provider", scopes: ["treeseed:read"] }),
-    buildRepositoryContext: resource("treedx.repositories.context.build", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/context/build", { projectId: z.string().min(1), repoId: z.string().min(1) }, { capability: "treedx.read", authentication: "oauth_or_provider", scopes: ["treeseed:read"] })
+    library: resource("treedx.library.show", "GET", "/v1/projects/{projectId}/treedx-library", { projectId: z.string().min(1) }, { capability: "treedx.read", surfaces: ["rest", "cli", "mcp_resource"] }),
+    bindLibrary: resource("treedx.library.bind", "POST", "/v1/projects/{projectId}/treedx-library", { projectId: z.string().min(1) }, { capability: "treedx.write", surfaces: ["rest", "cli"] }),
+    serviceContract: treedxProxy("treedx.service.contract", null, "GET", "/v1/dx/projects/{projectId}/service-contract", { projectId: z.string().min(1) }, { surfaces: ["rest", "cli", "mcp_resource"] }),
+    health: treedxProxy("treedx.health.show", "getHealth", "GET", "/v1/dx/projects/{projectId}/health", { projectId: z.string().min(1) }, { surfaces: ["rest", "cli", "mcp_tool", "mcp_resource"] }),
+    readiness: treedxProxy("treedx.readiness.show", "getReadiness", "GET", "/v1/dx/projects/{projectId}/readiness", { projectId: z.string().min(1) }, { surfaces: ["rest", "cli", "mcp_resource"] }),
+    version: treedxProxy("treedx.version.show", "getVersion", "GET", "/v1/dx/projects/{projectId}/version", { projectId: z.string().min(1) }, { surfaces: ["rest", "cli", "mcp_resource"] }),
+    capabilities: treedxProxy("treedx.capabilities.list", "listCapabilities", "GET", "/v1/dx/projects/{projectId}/capabilities", { projectId: z.string().min(1) }, { surfaces: ["rest", "cli", "mcp_tool", "mcp_resource"] }),
+    effectiveScope: treedxProxy("treedx.scope.show", "getEffectiveScope", "GET", "/v1/dx/projects/{projectId}/effective-scope", { projectId: z.string().min(1) }, { surfaces: ["rest", "mcp_resource"] }),
+    repositories: {
+      list: treedxProxy("treedx.repositories.list", "listRepositories", "GET", "/v1/dx/projects/{projectId}/repos", { projectId: z.string().min(1) }, { pagination: "cursor" }),
+      create: treedxProxy("treedx.repositories.create", "createRepository", "POST", "/v1/dx/projects/{projectId}/repos", { projectId: z.string().min(1) }),
+      show: treedxProxy("treedx.repositories.show", "getRepository", "GET", "/v1/dx/projects/{projectId}/repos/{repoId}", { projectId: z.string().min(1), repoId: z.string().min(1) }),
+      status: treedxProxy("treedx.repositories.status", "getRepositoryStatus", "GET", "/v1/dx/projects/{projectId}/repos/{repoId}/status", { projectId: z.string().min(1), repoId: z.string().min(1) }),
+      refs: treedxProxy("treedx.repositories.refs", "listRepositoryRefs", "GET", "/v1/dx/projects/{projectId}/repos/{repoId}/refs", { projectId: z.string().min(1), repoId: z.string().min(1) }),
+      sync: treedxProxy("treedx.repositories.sync", "syncRepository", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/sync", { projectId: z.string().min(1), repoId: z.string().min(1) }),
+      push: treedxProxy("treedx.repositories.push", "pushRepository", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/push", { projectId: z.string().min(1), repoId: z.string().min(1) }, { risk: "authority" }),
+      promoteRef: treedxProxy("treedx.repositories.refs.promote", "promoteRepositoryRef", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/refs/promote", { projectId: z.string().min(1), repoId: z.string().min(1) }, { risk: "authority" }),
+      retireRef: treedxProxy("treedx.repositories.refs.retire", "retireRepositoryRef", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/refs/retire", { projectId: z.string().min(1), repoId: z.string().min(1) }, { risk: "destructive" }),
+      readFiles: treedxProxy("treedx.repositories.files.read", "readRepositoryFile", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/files/read", { projectId: z.string().min(1), repoId: z.string().min(1) }, { read: true }),
+      listPaths: treedxProxy("treedx.repositories.paths.list", "listRepositoryPaths", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/paths/list", { projectId: z.string().min(1), repoId: z.string().min(1) }, { read: true, pagination: "cursor" }),
+      searchFiles: treedxProxy("treedx.repositories.files.search", "searchRepositoryFiles", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/files/search", { projectId: z.string().min(1), repoId: z.string().min(1) }, { read: true, pagination: "cursor" }),
+      query: treedxProxy("treedx.repositories.query", "queryRepository", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/query", { projectId: z.string().min(1), repoId: z.string().min(1) }, { read: true })
+    },
+    workspaces: {
+      list: treedxProxy("treedx.workspaces.list", null, "GET", "/v1/dx/projects/{projectId}/workspaces", { projectId: z.string().min(1) }, { surfaces: ["rest", "cli", "mcp_tool", "mcp_resource"], pagination: "cursor" }),
+      create: treedxProxy("treedx.workspaces.create", "createWorkspace", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/workspaces", { projectId: z.string().min(1), repoId: z.string().min(1) }),
+      show: treedxProxy("treedx.workspaces.show", "getWorkspace", "GET", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}", { projectId: z.string().min(1), workspaceId: z.string().min(1) }, { surfaces: ["rest", "cli", "mcp_tool", "mcp_resource"] }),
+      status: treedxProxy("treedx.workspaces.status", "getWorkspaceStatus", "GET", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/status", { projectId: z.string().min(1), workspaceId: z.string().min(1) }),
+      diff: treedxProxy("treedx.workspaces.diff", "getWorkspaceDiff", "GET", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/diff", { projectId: z.string().min(1), workspaceId: z.string().min(1) }),
+      tree: treedxProxy("treedx.workspaces.tree", "listWorkspaceTree", "GET", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/tree", { projectId: z.string().min(1), workspaceId: z.string().min(1) }),
+      close: treedxProxy("treedx.workspaces.close", "closeWorkspace", "POST", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/close", { projectId: z.string().min(1), workspaceId: z.string().min(1) }),
+      abandon: treedxProxy("treedx.workspaces.abandon", "abandonWorkspace", "POST", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/abandon", { projectId: z.string().min(1), workspaceId: z.string().min(1) }, { risk: "destructive", surfaces: ["rest", "cli", "mcp_tool"] })
+    },
+    files: {
+      read: treedxProxy("treedx.workspaces.files.read", "readWorkspaceFile", "GET", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/files", { projectId: z.string().min(1), workspaceId: z.string().min(1) }),
+      write: treedxProxy("treedx.workspaces.files.write", "writeWorkspaceFile", "PUT", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/files", { projectId: z.string().min(1), workspaceId: z.string().min(1) }),
+      writeBatch: treedxProxy("treedx.workspaces.files.batch", "writeWorkspaceFiles", "PUT", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/files/batch", { projectId: z.string().min(1), workspaceId: z.string().min(1) }),
+      patch: treedxProxy("treedx.workspaces.files.patch", "patchWorkspaceFile", "PATCH", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/files", { projectId: z.string().min(1), workspaceId: z.string().min(1) }),
+      remove: treedxProxy("treedx.workspaces.files.delete", "deleteWorkspaceFile", "DELETE", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/files", { projectId: z.string().min(1), workspaceId: z.string().min(1) }, { risk: "destructive" }),
+      search: treedxProxy("treedx.workspaces.files.search", "searchWorkspace", "POST", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/search", { projectId: z.string().min(1), workspaceId: z.string().min(1) }, { read: true, pagination: "cursor" }),
+      applyChangeset: treedxProxy("treedx.workspaces.changesets.apply", "applyWorkspaceChangeset", "POST", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/changesets", { projectId: z.string().min(1), workspaceId: z.string().min(1) }),
+      commit: treedxProxy("treedx.workspaces.commit", "commitWorkspace", "POST", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/commit", { projectId: z.string().min(1), workspaceId: z.string().min(1) })
+    },
+    blobs: {
+      read: treedxProxy("treedx.repositories.blobs.read", "readRepositoryBlob", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/blobs/read", { projectId: z.string().min(1), repoId: z.string().min(1) }, { read: true }),
+      write: treedxProxy("treedx.workspaces.blobs.write", "writeWorkspaceBlob", "POST", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/blobs/write", { projectId: z.string().min(1), workspaceId: z.string().min(1) }),
+      remove: treedxProxy("treedx.workspaces.blobs.delete", "deleteWorkspaceBlob", "POST", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/blobs/delete", { projectId: z.string().min(1), workspaceId: z.string().min(1) }, { risk: "destructive" }),
+      download: treedxProxy("treedx.workspaces.blobs.download", "downloadWorkspaceBlob", "GET", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/blobs/download", { projectId: z.string().min(1), workspaceId: z.string().min(1) }, { surfaces: ["rest", "mcp_tool"] }),
+      upload: treedxProxy("treedx.workspaces.blobs.upload", "uploadWorkspaceBlob", "PUT", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/blobs/upload", { projectId: z.string().min(1), workspaceId: z.string().min(1) }),
+      createUpload: treedxProxy("treedx.workspaces.blobs.uploads.create", "createWorkspaceBlobUpload", "POST", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/blobs/uploads", { projectId: z.string().min(1), workspaceId: z.string().min(1) }),
+      uploadPart: treedxProxy("treedx.workspaces.blobs.uploads.parts.write", "uploadWorkspaceBlobPart", "PUT", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/blobs/uploads/{uploadId}/parts/{partNumber}", { projectId: z.string().min(1), workspaceId: z.string().min(1), uploadId: z.string().min(1), partNumber: z.string().min(1) }),
+      completeUpload: treedxProxy("treedx.workspaces.blobs.uploads.complete", "completeWorkspaceBlobUpload", "POST", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/blobs/uploads/{uploadId}/complete", { projectId: z.string().min(1), workspaceId: z.string().min(1), uploadId: z.string().min(1) }),
+      abortUpload: treedxProxy("treedx.workspaces.blobs.uploads.abort", "abortWorkspaceBlobUpload", "DELETE", "/v1/dx/projects/{projectId}/workspaces/{workspaceId}/blobs/uploads/{uploadId}", { projectId: z.string().min(1), workspaceId: z.string().min(1), uploadId: z.string().min(1) }, { risk: "destructive" })
+    },
+    graph: {
+      refresh: treedxProxy("treedx.repositories.graph.refresh", "refreshRepositoryGraph", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/graph/refresh", { projectId: z.string().min(1), repoId: z.string().min(1) }),
+      refreshJob: treedxProxy("treedx.repositories.graph.jobs.show", "getGraphRefreshJob", "GET", "/v1/dx/projects/{projectId}/repos/{repoId}/graph/jobs/{jobId}", { projectId: z.string().min(1), repoId: z.string().min(1), jobId: z.string().min(1) }),
+      query: treedxProxy("treedx.repositories.graph.query", "queryRepositoryGraph", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/graph/query", { projectId: z.string().min(1), repoId: z.string().min(1) }, { read: true }),
+      node: treedxProxy("treedx.repositories.graph.nodes.show", "getGraphNode", "GET", "/v1/dx/projects/{projectId}/repos/{repoId}/graph/nodes/{nodeId}", { projectId: z.string().min(1), repoId: z.string().min(1), nodeId: z.string().min(1) }),
+      related: treedxProxy("treedx.repositories.graph.related", "getRelatedGraphNodes", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/graph/related", { projectId: z.string().min(1), repoId: z.string().min(1) }, { read: true }),
+      subgraph: treedxProxy("treedx.repositories.graph.subgraph", "getGraphSubgraph", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/graph/subgraph", { projectId: z.string().min(1), repoId: z.string().min(1) }, { read: true }),
+      searchFiles: treedxProxy("treedx.repositories.graph.files.search", "searchGraphFiles", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/graph/search/files", { projectId: z.string().min(1), repoId: z.string().min(1) }, { read: true }),
+      searchSections: treedxProxy("treedx.repositories.graph.sections.search", "searchGraphSections", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/graph/search/sections", { projectId: z.string().min(1), repoId: z.string().min(1) }, { read: true }),
+      searchEntities: treedxProxy("treedx.repositories.graph.entities.search", "searchGraphEntities", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/graph/search/entities", { projectId: z.string().min(1), repoId: z.string().min(1) }, { read: true })
+    },
+    context: {
+      build: treedxProxy("treedx.repositories.context.build", "buildContext", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/context/build", { projectId: z.string().min(1), repoId: z.string().min(1) }, { read: true }),
+      parse: treedxProxy("treedx.repositories.context.parse", "parseContextQuery", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/context/parse", { projectId: z.string().min(1), repoId: z.string().min(1) }, { read: true })
+    },
+    federated: {
+      search: treedxProxy("treedx.federated.search", "federatedSearch", "POST", "/v1/dx/projects/{projectId}/search", { projectId: z.string().min(1) }, { read: true, pagination: "cursor" }),
+      query: treedxProxy("treedx.federated.query", "federatedQuery", "POST", "/v1/dx/projects/{projectId}/query", { projectId: z.string().min(1) }, { read: true }),
+      context: treedxProxy("treedx.federated.context", "federatedContextBuild", "POST", "/v1/dx/projects/{projectId}/context", { projectId: z.string().min(1) }, { read: true }),
+      graph: treedxProxy("treedx.federated.graph", "federatedGraphQuery", "POST", "/v1/dx/projects/{projectId}/graph", { projectId: z.string().min(1) }, { read: true })
+    },
+    snapshots: {
+      build: treedxProxy("treedx.repositories.snapshots.build", "buildSnapshot", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/snapshots", { projectId: z.string().min(1), repoId: z.string().min(1) }),
+      show: treedxProxy("treedx.repositories.snapshots.show", "getSnapshot", "GET", "/v1/dx/projects/{projectId}/repos/{repoId}/snapshots/{snapshotId}", { projectId: z.string().min(1), repoId: z.string().min(1), snapshotId: z.string().min(1) })
+    },
+    artifacts: {
+      export: treedxProxy("treedx.repositories.artifacts.export", "exportArtifact", "POST", "/v1/dx/projects/{projectId}/repos/{repoId}/artifacts", { projectId: z.string().min(1), repoId: z.string().min(1) }),
+      list: treedxProxy("treedx.repositories.artifacts.list", "listArtifacts", "GET", "/v1/dx/projects/{projectId}/repos/{repoId}/artifacts", { projectId: z.string().min(1), repoId: z.string().min(1) }, { pagination: "cursor" }),
+      show: treedxProxy("treedx.repositories.artifacts.show", "getArtifact", "GET", "/v1/dx/projects/{projectId}/repos/{repoId}/artifacts/{artifactId}", { projectId: z.string().min(1), repoId: z.string().min(1), artifactId: z.string().min(1) }),
+      remove: treedxProxy("treedx.repositories.artifacts.delete", "deleteArtifact", "DELETE", "/v1/dx/projects/{projectId}/repos/{repoId}/artifacts/{artifactId}", { projectId: z.string().min(1), repoId: z.string().min(1), artifactId: z.string().min(1) }, { risk: "destructive" })
+    },
+    searchIndex: {
+      status: treedxProxy("treedx.repositories.search.index.status", "getSearchIndexStatus", "GET", "/v1/dx/projects/{projectId}/repos/{repoId}/search-index", { projectId: z.string().min(1), repoId: z.string().min(1) })
+    }
   },
   providers: {
     register: noPathProvider("providers.register", "POST", "/v1/provider-registrations", { redactedPaths: ["body.registrationKey"] }),

package/dist/operator-contracts/operation-builder.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { type ControlPlaneOperationBinding, type ControlPlaneOperationDescriptor } from './control-plane-operation.js';
+type Definition = Omit<ControlPlaneOperationDescriptor, 'schemaVersion' | 'schemas' | 'idempotency' | 'concurrency' | 'audited' | 'receipt' | 'redactedPaths' | 'authentication'> & {
+    parameters?: string;
+    redactedPaths?: string[];
+    idempotencyRequired?: boolean;
+    concurrencyRequired?: boolean;
+    authentication?: ControlPlaneOperationDescriptor['authentication'];
+};
+export declare function defineOperation<TPath, TQuery, TBody, TOutput>(definition: Definition, schema: ControlPlaneOperationBinding<TPath, TQuery, TBody, TOutput>['schema']): ControlPlaneOperationBinding<TPath, TQuery, TBody, TOutput>;
+export declare function defineTreeDxProxyOperation<T extends z.ZodRawShape>(operationId: `${string}.${string}`, upstreamOperationId: string | null, method: 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT', path: `/v1/${string}`, pathShape: T, options?: {
+    read?: boolean;
+    risk?: ControlPlaneOperationDescriptor['riskClass'];
+    surfaces?: ControlPlaneOperationDescriptor['surfaces'];
+    pagination?: ControlPlaneOperationDescriptor['pagination'];
+}): ControlPlaneOperationBinding<z.objectUtil.addQuestionMarks<z.baseObjectOutputType<T>, any> extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never, {}, Record<string, unknown> | undefined, Record<string, unknown>>;
+export {};

package/dist/operator-contracts/operation-builder.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { TREEDX_OPENAPI_CONTRACT } from "@treeseed/treedx/openapi";
+import {
+  CONTROL_PLANE_OPERATION_SCHEMA_VERSION
+} from "./control-plane-operation.js";
+function defineOperation(definition, schema) {
+  const { parameters, redactedPaths = [], idempotencyRequired, concurrencyRequired, ...descriptor } = definition;
+  const mutation = definition.kind === "mutation";
+  return {
+    descriptor: {
+      ...descriptor,
+      authentication: definition.authentication ?? (definition.oauthScopes.length ? "oauth" : "anonymous"),
+      schemaVersion: CONTROL_PLANE_OPERATION_SCHEMA_VERSION,
+      schemas: {
+        input: `treeseed.${definition.operationId}.input/v1`,
+        output: `treeseed.${definition.operationId}.output/v1`,
+        errors: "treeseed.problem/v1",
+        ...parameters ? { parameters } : {}
+      },
+      idempotency: { required: idempotencyRequired ?? mutation, header: "Idempotency-Key" },
+      concurrency: { required: concurrencyRequired ?? false, readHeader: "ETag", writeHeader: "If-Match" },
+      audited: definition.surfaces.some((surface) => surface !== "internal"),
+      receipt: mutation,
+      redactedPaths
+    },
+    schema
+  };
+}
+const empty = z.object({}).strict();
+const none = z.undefined();
+const record = z.record(z.unknown());
+function defineTreeDxProxyOperation(operationId, upstreamOperationId, method, path, pathShape, options = {}) {
+  const kind = options.read ?? method === "GET" ? "read" : "mutation";
+  const riskClass = options.risk ?? "ordinary";
+  return defineOperation({
+    operationId,
+    description: `${kind === "read" ? "Read" : "Apply"} ${operationId} through the project-scoped TreeDX proxy.`,
+    rest: { method, path },
+    ...Object.keys(pathShape).length ? { parameters: `treeseed.${operationId}.parameters/v1` } : {},
+    capability: kind === "read" ? "treedx.read" : "treedx.write",
+    authentication: "oauth_or_provider",
+    oauthScopes: kind === "read" ? ["treeseed:read"] : ["treeseed:projects:write"],
+    kind,
+    riskClass,
+    confirmation: riskClass === "ordinary" ? "never" : "input_required",
+    surfaces: options.surfaces ?? ["rest", "mcp_tool", ...method === "GET" ? ["mcp_resource"] : []],
+    cacheScope: kind === "read" ? "project" : "none",
+    pagination: options.pagination ?? "none",
+    ...upstreamOperationId ? { upstream: { service: "treedx", operationId: upstreamOperationId, contractVersion: TREEDX_OPENAPI_CONTRACT.openapiVersion, contractDigest: TREEDX_OPENAPI_CONTRACT.openapiSha256 } } : {}
+  }, {
+    path: z.object(pathShape).strict(),
+    query: method === "GET" ? record : empty,
+    body: method === "GET" ? none : record,
+    output: record
+  });
+}
+export {
+  defineOperation,
+  defineTreeDxProxyOperation
+};