feat: idempotent workspace creation — same name+owner returns existing (#115)

* feat: idempotent workspace creation — same name+owner returns existing

Same API key + same name returns existing workspace (200).
Different API keys can share workspace names.

Changes:
- engine/workspace.ts — createWorkspace returns existing if same name+apiKeyHash
- routes/workspace.ts — returns 200 for existing, 201 for new
- sdk relay.ts — ensureWorkspace simplified (no 409 dependency)
- local main.rs — matches server idempotent behavior
- types/workspace.ts — CreateWorkspaceResult type
- openapi.yaml — updated responses (200 added, 409 removed)
- README.md — updated docs
- tests updated

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: add engine integration tests for idempotent workspace creation

Tests with real SQLite DB (via FakeD1):
- New workspace returns created: true
- Same name + same API key returns existing (created: false)
- Same name + different keys creates separate workspaces
- ownerApiKeyHash lookup works
- Anonymous creates always produce new workspaces
- Conflicting key + hash throws
- getWorkspaceByName handles duplicates

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* update openapi

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: khaliqgant

README.md

@@ -88,13 +88,17 @@ npx tsx quickstart.ts
 
 That is the canonical onboarding loop: create workspace, register agents, connect realtime streams, and watch messages flow live.
 
-If you want idempotent setup by workspace name, use `ensureWorkspace()`:
+Workspace names are not globally unique. Workspace creation is idempotent for the same workspace name and API key: repeating that combination returns the existing workspace instead of creating another one.
+
+If you want an explicit SDK helper that tells you whether setup returned an existing workspace or created a new one, use `ensureWorkspace()`:
 
 ```ts
-const ensured = await RelayCast.ensureWorkspace('my-project');
+const ensured = await RelayCast.ensureWorkspace('my-project', {
+  apiKey: knownWorkspaceKey,
+});
 
 if (ensured.existed) {
-  console.log(`Workspace already exists as ${ensured.id}`);
+  console.log(`Workspace already exists as ${ensured.workspaceId}`);
   // Existing workspace keys are not recoverable from the API.
   // Reuse the known rk_live_* key you already have for this workspace.
 } else {
@@ -248,7 +252,9 @@ Remote Streamable HTTP config:
 ## REST Quick Start
 
 ```bash
-# Create workspace (names must be unique)
+# Create workspace
+# Workspace names are not globally unique.
+# Reusing the same name with the same Authorization bearer workspace key returns the existing workspace.
 curl -X POST https://api.relaycast.dev/v1/workspaces \
   -H "Content-Type: application/json" \
   -d '{"name": "my-project"}'

openapi.yaml

@@ -50,6 +50,22 @@ components:
           type: string
           format: date-time
 
+    CreateWorkspaceResponse:
+      type: object
+      required:
+        - workspace_id
+        - created_at
+      properties:
+        workspace_id:
+          type: string
+          description: Snowflake ID of the workspace
+        api_key:
+          type: string
+          description: Workspace API key (only returned on first creation)
+        created_at:
+          type: string
+          format: date-time
+
     WorkspaceLookup:
       type: object
       required:
@@ -345,9 +361,12 @@ paths:
   /workspaces:
     post:
       summary: Create workspace
-      description: Create a new workspace and get an API key. Workspace names must be unique.
+      description: Create a workspace and get an API key when a new workspace is created. This operation is idempotent by workspace name for the same bearer workspace key: if you repeat the call with the same name and the same `Authorization: Bearer rk_*` key, the existing workspace is returned with a `200` response; otherwise a new workspace is created and returned with a `201` response.
       tags:
         - Workspaces
+      security:
+        - {}
+        - workspaceKey: []
       requestBody:
         required: true
         content:
@@ -360,6 +379,17 @@ paths:
                 name:
                   type: string
       responses:
+        '200':
+          description: Existing workspace returned (idempotent)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok:
+                    type: boolean
+                  data:
+                    $ref: '#/components/schemas/CreateWorkspaceResponse'
         '201':
           description: Workspace created
           content:
@@ -370,19 +400,13 @@ paths:
                   ok:
                     type: boolean
                   data:
-                    $ref: '#/components/schemas/Workspace'
+                    $ref: '#/components/schemas/CreateWorkspaceResponse'
         '400':
           description: Invalid request
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
-        '409':
-          description: Workspace name already exists
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
 
   /workspaces/by-name/{name}:
     get: