# API Contract: Metadata-Only Cloud Linker

**Version:** 1.0.0
**Status:** Draft
**Component:** `clew-engine` <-> `clew-platform`

## 1. Overview
This contract defines how `clew-engine` sends structural metadata ("Signatures") to `clew-platform` to enable Cross-Repo Dependency Linking without transmitting source code.

## 2. Terminology
- **Export Signature:** A symbol defined in the repo that is visible to other repos (e.g., `public class User`).
- **Import Signature:** A symbol referenced by the repo that is expected to be defined elsewhere (e.g., `import { User } from 'auth-lib'`).
- **USP (Unique Symbol Path):** A deterministic string interacting the symbol's location. Format: `package:module:path:symbol`.

## 3. Data Models

### 3.1 SymbolType
Enum: `["class", "function", "variable", "interface", "type"]`

### 3.2 Signature Object
```json
{
  "file_path": "src/services/auth.py",
  "symbol_name": "AuthService",
  "symbol_type": "class",
  "usp": "src/services/auth.py:AuthService",
  "line_no": 42
}
```
*Note: We do NOT send the code body.*

## 4. API Endpoints

### 4.1 Ingest Signatures
**POST** `/v1/fleet/signatures`

**Auth:** Bearer Token (Worker Key)

**Request Body:**
```json
{
  "repo_id": "123e4567-e89b-12d3-a456-426614174000",
  "commit_hash": "a1b2c3d4...",
  "exports": [
    {
      "file_path": "src/core.py",
      "symbol_name": "BaseController",
      "symbol_type": "class",
      "usp": "src/core.py:BaseController"
    }
  ],
  "imports": [
    {
      "file_path": "src/plugin.py",
      "symbol_name": "BaseController",
      "source_module": "clew_core",  // The library being imported from
      "line_no": 10
    }
  ]
}
```

**Response:**
```json
{
  "status": "processed",
  "links_found": 5,
  "external_edges": [
    {
      "source_file": "src/plugin.py",
      "source_line": 10,
      "target_repo_id": "987fcdeb-51a2...",
      "target_file": "src/core.py",
      "target_symbol": "BaseController"
    }
  ]
}
```

## 5. Security Validation
1.  **No Code:** The Platform REJECTS any payload containing fields like `body`, `code`, or `content`.
2.  **Hashing:** (Optional Future) If clients are paranoid, `usp` can be hashed (`sha256(usp)`). For V1, we transmit plain strings for debuggability.
