fix(api): align maintained CodeAPI contracts

api/openapi.yaml

@@ -1,12 +1,17 @@
-openapi: 3.0.0
+openapi: 3.0.3
 info:
-  title: Code Execution API
-  version: 1.0.0
+  title: CodeAPI Internal Sandbox Runner API
+  version: 2.0.0
+  description: >-
+    Internal service-to-sandbox contract. This API is not a public client
+    surface. The public authenticated contract is service/openapi.yml.
+x-internal: true
 
 paths:
-  /execute:
+  /api/v2/execute:
     post:
-      summary: Execute code
+      summary: Execute a prepared sandbox job
+      operationId: executeSandboxJob
       requestBody:
         required: true
         content:
@@ -15,80 +20,214 @@ paths:
               $ref: '#/components/schemas/ExecuteRequest'
       responses:
         '200':
-          description: Successful execution
+          description: Sandbox execution result
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ExecuteResponse'
         '400':
-          description: Bad request
+          description: Invalid execution request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          description: Missing execution manifest
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '403':
+          description: Invalid or forbidden execution manifest
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '409':
+          description: Runtime session workspace conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '413':
+          description: Request body exceeds the configured limit
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '415':
+          description: JSON content type required
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
         '500':
-          description: Internal server error
+          description: Sandbox execution failed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
 
 components:
   schemas:
+    Error:
+      type: object
+      required: [message]
+      properties:
+        message:
+          type: string
+        error:
+          type: string
+
     ExecuteRequest:
       type: object
-      required:
-        - language
-        - version
-        - files
+      required: [language, version, files]
       properties:
         session_id:
           type: string
+          description: Top-level execution session identifier.
+        output_session_id:
+          type: string
+          description: Storage session for generated files.
         language:
           type: string
         version:
           type: string
-        files:
+        args:
           type: array
           items:
-            $ref: '#/components/schemas/File'
+            type: string
         stdin:
           type: string
-        args:
+        files:
           type: array
           items:
-            type: string
-        compileTimeout:
+            $ref: '#/components/schemas/InputFile'
+        compile_memory_limit:
+          type: integer
+        run_memory_limit:
           type: integer
-        runTimeout:
+        run_timeout:
           type: integer
-        compileMemoryLimit:
+        compile_timeout:
           type: integer
-        runMemoryLimit:
+        run_cpu_time:
           type: integer
-
-    File:
+        compile_cpu_time:
+          type: integer
+        env_vars:
+          type: object
+          additionalProperties:
+            type: string
+        egress_grant:
+          type: string
+          description: Opaque internal egress capability.
+        execution_manifest:
+          type: string
+          description: Signed internal execution scope.
+        tool_call_socket:
+          type: boolean
+
+    InputFile:
       type: object
-      required:
-        - name
-        - content
+      oneOf:
+        - required: [content]
+        - required: [id, storage_session_id]
       properties:
-        name:
-          type: string
         id:
           type: string
+          description: Storage object identifier for a by-reference input.
+        storage_session_id:
+          type: string
+          description: Storage session for a by-reference input.
+        input_cache_key:
+          type: string
+          pattern: '^[0-9a-f]{64}$'
+          description: Stable SHA-256 runner-local cache identity.
+        name:
+          type: string
+          description: Optional destination path; the runner supplies a default when omitted.
         content:
           type: string
+          description: Inline file content.
         encoding:
           type: string
           enum: [base64, hex, utf8]
-
-    ExecuteResponse:
+        entity_id:
+          type: string
+          description: Caller authorization scope echoed on inherited outputs.
+
+    FileRef:
       type: object
+      required: [id, name, storage_session_id]
       properties:
-        compile:
-          $ref: '#/components/schemas/ExecutionStage'
-        run:
-          $ref: '#/components/schemas/ExecutionStage'
-
+        id:
+          type: string
+        name:
+          type: string
+        storage_session_id:
+          type: string
+        modified_from:
+          type: object
+          required: [id, storage_session_id]
+          properties:
+            id:
+              type: string
+            storage_session_id:
+              type: string
+        inherited:
+          type: boolean
+          enum: [true]
+        entity_id:
+          type: string
+
     ExecutionStage:
       type: object
+      required: [stdout, stderr, output]
       properties:
         stdout:
           type: string
         stderr:
           type: string
-        exitCode:
+        code:
+          type: integer
+          nullable: true
+        signal:
+          type: string
+          nullable: true
+        output:
+          type: string
+        memory:
           type: integer
+          nullable: true
+        message:
+          type: string
+          nullable: true
+        status:
+          type: string
+          nullable: true
+        cpu_time:
+          type: number
+          nullable: true
+        wall_time:
+          type: number
+          nullable: true
+
+    ExecuteResponse:
+      type: object
+      required: [language, version, session_id, files]
+      properties:
+        compile:
+          $ref: '#/components/schemas/ExecutionStage'
+        run:
+          $ref: '#/components/schemas/ExecutionStage'
+        language:
+          type: string
+        version:
+          type: string
+        session_id:
+          type: string
+        files:
+          type: array
+          items:
+            $ref: '#/components/schemas/FileRef'

docs/fork/patches.md

@@ -29,6 +29,7 @@ States: Active, Review on sync, Draft, History only, Retired.
 | Keep PVC package initialization Argo-safe | Active | `646ed2e`, `12d3760`, `c1509a8` | Upstream `packages.source=pvc` mode |
 | Recover job completion when BullMQ events lag | Active | `b66e87e` | Upstream execution profiles and completion timeout |
 | Reconnect the egress ledger after Redis outages | Active | `5e459dd` | Managed Redis |
+| Keep public and sandbox wire contracts distinct | Draft | `0b66a3a`, `3ac5e8f` | Optional upstream contract maintenance |
 
 ## Publish exact-SHA UZH images
 
@@ -280,6 +281,61 @@ Replay and drop condition:
   recreates the Redis client after terminal disconnect, with a readiness
   recovery test covering an outage longer than five attempts.
 
+## Keep public and sandbox wire contracts distinct
+
+Required behavior:
+
+- Keep this package optional and runtime-neutral. No UZH feature, source gate,
+  image, or deployment depends on it.
+- Preserve the established exported `ExecuteResponse` sandbox transport while
+  naming the flat `/v1/exec` result `PublicExecuteResponse` for service-owned
+  producers and consumers.
+- Describe the public execution, upload, batch-upload, listing, metadata,
+  deletion, and download wire shapes separately from the internal
+  `/api/v2/execute` contract.
+- Keep the internal input filename optional and distinguish inline inputs from
+  stored-file references in the schema.
+
+Owned paths:
+
+- `api/openapi.yaml`
+- `service/openapi.yml`
+- `service/src/openapi-contract.test.ts`
+
+Shared paths:
+
+- `service/src/service/programmatic-router.ts`
+- `service/src/service/replay-state.ts`
+- `service/src/types/service.ts`
+- `service/src/workers.ts`
+
+Source and current-upstream evidence:
+
+- Commit `0b66a3a722bdafbcb48b8a32f91bb2ae0997a685` defines the separate public
+  type, corrected OpenAPI documents, and contract tests. Commit
+  `3ac5e8fec1fb7d551ca903aab259be9c983bdd69` removes the runtime response
+  change so this package remains contract maintenance only.
+- The root, API, and service manifests at baseline
+  `83c4f7b105b6b3e69eda12701ad4ec437acba08f` have no package exports or
+  `publishConfig`; these are deployed applications, not published libraries.
+- Complete-tree searches at the UZH baseline and upstream
+  `297fead1a0cd997b0e3e6e55f77fbe83b376be1a` found `ExecuteResponse` only in
+  its definition, OpenAPI names, and the internal sandbox backend adapter.
+- GitHub searches across `uzh-bf` found no external `ExecuteResponse` or direct
+  source import. The upstream fork network search found the same type
+  definition in eight indexed forks and no separate consumer contract.
+- GitLab searches of `ai-infrastructure/deployment` and local AI and Klicker
+  source-checkout searches found no `ExecuteResponse` or direct import from the
+  CodeAPI source tree. The legacy export remains unchanged regardless.
+
+Replay and drop condition:
+
+- Reapply the public schemas around the current service routes and the internal
+  schema around the current sandbox request validator; do not rename the
+  established sandbox transport for source consumers.
+- Drop when upstream publishes equivalent public and internal schemas, a
+  separately named flat public type, and matching executable contract tests.
+
 ## Retired debris
 
 - Merge commit `356123a` is history-only transport for the package-init fix;
@@ -295,6 +351,7 @@ Replay and drop condition:
 - Every one of the 23 paths in the active merge-base-to-fork final-tree diff is
   assigned above. The chart values, package resources, worker deployment, queue
   module, and two routers are named shared seams in every contributing patch.
-- Fork-authored non-merge commits were collapsed into the seven logical final
-  behaviors above. The only fork merge commit is classified as history-only;
-  no fork-authored final-tree path is left unowned.
+- Fork-authored non-merge commits were collapsed into the seven historical
+  logical behaviors above. This branch adds one public-contract behavior with
+  eight owned or shared paths. The only fork merge commit is classified as
+  history-only; no fork-authored final-tree path is left unowned.