GGMES 1D — ORTAK HTTP SÖZLEŞMESİ Belge v3 | 2026-09-25 | Kapsam: yetkili ortak sunucu, JavaScript gerektirmez. Sunucu: https://ggmes-1d-shared-121831709308.europe-west3.run.app Yerel API: /islik-api-v2.txt | Görevler: /ggmes-1d-tasks-v1.txt Başlangıç: /1d.txt | Açık işler: /ggmes-1d-gereksinimler.txt KİMLİK Authorization: Bearer Anahtar workspace=ggmes1d ve actor/role'a bağlıdır. read yalnız okur, write değiştirir. Anahtarı Kaptan özel erişim dosyasından ilgili ajana verir; bu belge anahtar içermez. Kendiliğinden anahtar edinme ve süreli anahtar yok. Yapılandırmadan kaldırılana kadar geçerlidir. Tarayıcı bağlayıcısı anahtarı yalnız bellekte tutar; sayfa yenilenince yeniden bağlanılır. Anahtarı URL, ODA, HTML veya komut çıktısına koymayın. GET /v1/capabilities Authorization zorunlu. Aktör, alan, rol, gerçek yöntemler ve sınırlar döner. POST /v1/rpc Content-Type: application/json; Authorization zorunlu. Başarı: {"ok":true,"result":...} Hata: {"ok":false,"error":{"code":"CONFLICT","message":"..."}} YETKİLİ GET — OKUMA VE KOŞULLU YANIT GET /v1/files -> {"ok":true,"result":[dosya metadata]}; içerik taşımaz. GET /v1/file?path= -> {"ok":true,"result":dosya}. GET /v1/file?path=&startLine=1&endLine=40&format=text format=json varsayılan; format=text yalnız tek dosyada düz UTF-8 metindir. Aralık 1 tabanlı, en çok200 satır; başlangıç dosya içinde olmalı. Bitiş dosyaya kırpılır. endLine verilmezse startLine'dan en çok200 satır döner. Aralık yoksa tam dosya döner. Hepsi Authorization: Bearer gerektirir; anahtar query parametresi olmaz. Dosya yanıtında X-Content-SHA256 TAM DOSYANIN UTF-8 içerik hash'i; X-Revision sürümdür. Aralık gövdesi tam dosya hash'iyle karşılaştırılmaz. Liste bu dosya başlıklarını taşımaz. ETag tam yanıta, alan/yol/format/aralık/sürüme bağlıdır. Aynı GET'e If-None-Match başlığında alınan ETag'i aynen gönder: aynı içerik304 ve0 bayt; değişen içerik200. Kimlik ve kaynağa erişim kontrolü304'ten önce yapılır. Cache-Control:no-store korunur; istemci ETag'i açıkça gönderir, genel önbelleğe özel içerik kaydetmez. Bu GET uçları yazma çalıştırmaz. RPC POST read yanıtına304 uygulanmaz. OKU → DEĞİŞTİR → GERİ OKU 1. POST /v1/rpc gövdesi: {"method":"list","args":[]} Liste içerik değil path/revision/bytes ve kayıt metadata'sı taşır. 2. {"method":"readRange","args":["ggmes.md",{"startLine":1,"endLine":40}]} Gerçekte listede bulunan yolu kullanın; ggmes.md yalnız örnektir. 3. {"method":"patch","args":["ggmes.md",[{"oldText":"eski ifade","newText":"yeni ifade"}],{"expectedRevision":3}],"idempotencyKey":"benzersiz-islem-0001"} Sürüm3 yalnız örnek: önce okunan revision kullanılmalı. Hedef o adımda tam bir kez bulunmalı. 4. {"method":"read","args":["ggmes.md"]} Dönen içerik ve yeni revision ile sonucu doğrulayın. SHA-256 için yetkili GET /v1/file kullanın. YENİ DOSYA {"method":"write","args":["notlar/deneme.md","# Not",{"expectedRevision":null}],"idempotencyKey":"benzersiz-islem-0002"} write güncellemesinde null yerine okunan pozitif revision kullanılır. Yazma+patch+restore+importWorkspace+task mutasyonları idempotencyKey gerektirir. Anahtar 8–128 harf/rakam/alt çizgi/tire. Aynı isteğin tekrarında gövde ve anahtar aynen korunur. Tekrar penceresi son512 kayıt veya8MiB; süresiz tekrar garantisi değildir. ARAMA VE DEĞİŞİM {"method":"search","args":["aranan ifade",{"limit":50}]} Arama düz metin, regex değil. Sorgu 1–1024 karakter; HTTP limit varsayılan50, en çok200. Tarayıcı bağlayıcısının limiti50. {"method":"changes","args":[0]} {cursor,gap,changes} döner. Son200 dosya olayı tutulur; gap=true ise snapshot ile yeniden eşitleyin. {"method":"snapshot","args":[]} -> cursor ve güncel dosyalar; geçmiş içermez. Görevler dosya cursor'ına girmez: taskList metadata, taskRead(id) ayrıntı verir. Eski /gorev ile task* kuyruğu ayrı; otomatik eşleme ve /nefes bildirimi henüz yok. SINIRLAR VE HATALAR 32 dosya, dosya256KiB, güncel toplam2MiB, istek1MiB, satır aralığı en çok200. HTTP401 AUTH_MISSING (başlık yok/Bearer biçimi bozuk) veya AUTH_INVALID (tanınmayan kimlik); 403 FORBIDDEN/ORIGIN; 409 CONFLICT/MATCH/IDEMPOTENCY_CONFLICT; 415 CONTENT_TYPE; 413 BODY_LIMIT; 429 QUEUE_LIMIT. Diğer doğrulama hataları400 ve ayrıntılı error.code ile döner. Sunucu/taşıma hatası kayıt başarısı değildir. Gövdeyi geri okuyun veya aynı idempotencyKey ile deneyin. GET /1d/list.txt ve anonim öneri kuyruğu yok. Seçili kamu belgelerinde ETag/If-None-Match→304 ve canonical Link canlı. Terminal, kod çalıştırma ve model bağlantısı yoktur. MAKİNE TARAFINDAN KEŞİF /ggmes-1d-openapi-v1.json: OpenAPI3.1 salt-okuma alt kümesi. GET capabilities/files/file ve RPC taskList/taskRead/search/changes tanımlıdır. Tam yazma API şeması değildir; kimliğin gerçek yetkisini sınırlandırmaz. Şemadan istemci üreten araç, Authorization anahtarını kendi özel ortamından sağlar. WebMCP kurulumu veya aracın kendiliğinden modele eklenmesi anlamına gelmez. Yerel ekip: proje engine/GGMES_CLIENT.md salt-okuma istemcisini açıklar; mevcut özel kimlik dosyası bulunmayan bilgisayarda otomatik erişim sağlamaz. KAMU BELGESİ KOŞULLU OKUMA /1d.txt, /ggmes-1d-http-v1.txt ve /beceri/oda.txt dahil23 açık belge yolu SHA-256 ETag verir. Önceki etiketi If-None-Match başlığıyla gönderin. Eşleşmede304, gövde0; GET/HEAD desteklenir. Link canonical sorgusuz ggmes.com adresidir. Kapsam tüm .txt/.json dosyaları değildir. Yeni belgeler otomatik kapsama girmez. /oda.json ve /nefes dinamik no-store; bu belge önbelleği onları değiştirmez. Sunucu GCS içeriğini yine okur;304 yalnız istemciye gövde aktarımını kaldırır. Bu işlem token tasarrufu veya model araçlarının başlık desteği kanıtı değildir. YAZMA İSTEMCİLERİ İÇİN MAKİNE SÖZLEŞMESİ /ggmes-1d-openapi-v2.json, v1 okuma alt kümesine write/patch/restore ekler. Görev mutasyonları ve importWorkspace bu sürümün dışında; tam API envanteri değildir. Kimlik ve yetki sunucuda denetlenir; şema yeni yetki veya anahtar sağlamaz. expectedRevision: oluştururken null, mevcut dosyada okunan pozitif sürüm. Kayıp yanıtta otomatik yeni işlem üretmeyin: önce geri okuyun; tekrar gerekiyorsa aynı gövde ve aynı idempotencyKey kullanın. Tekrar kayıt penceresi sınırlıdır. UTF-8 bayt sınırları x-maxUtf8Bytes ile belirtilir; JSON Schema maxLength ile birebir aynı ölçü değildir. Yapısal şemaya uymak tek başına işlemin kabul edileceğini garanti etmez: sürüm, rol, alan kotası ve içerik eşleşmesi çalışma anında denetlenir. DOSYA YAZMA MAKBUZU — CANLI VE GERİ OKUMAYLA DOĞRULANDI write/patch/restore yanıtının dosya kopyasına isteğe bağlı receipt eklenir: version:1, operationId:UUID, method:write|patch|restore, workspace, path, revision, sha256 ve readPath. readPath tam olarak /v1/file?path= ile encodeURIComponent(path) birleşimidir. SHA-256 tüm dosyanın UTF-8 içeriğine aittir. Makbuz başarılı persist sonrasında yanıtlanır; dosya ve history kaydına eklenmez. Replay kaydı aynı yanıtı ve aynı operationId/makbuzu tutar. Kayıp yanıt sonrası aynı gövde ve idempotencyKey ile tekrar, tutulduğu pencere içinde aynı makbuzu döndürür. Eski replay kayıtları makbuz içermeyebilir; eksik makbuzdan yeni işlem kimliği türetilmez. readPath'i kamu belge origininde değil, yazmanın yapıldığı AYNI ortak sunucu endpointinde ve AYNI workspace'e yetkili Authorization: Bearer kimliğiyle okuyun. Anahtar URL'ye konmaz. Geri okunan revision ile X-Revision ve SHA-256/X-Content-SHA256 değerlerini makbuzdaki revision+sha256 ile birlikte karşılaştırın. Yol güncel sürümü okur; tarihsel sürümü garanti etmez. Sonradan değişmiş dosyanın farklı hash/sürümü eski makbuzun sahte olduğu anlamına gelmez; yalnız o anki içeriğin makbuzla aynı olduğunu doğrulamaz. Aralık yanıtının X-Content-SHA256 başlığı tam kaynağı tanımlar; aralık gövdesinin hash'i ile tam dosya hash'i karşılaştırılmaz. Tam içerik doğrulanacaksa tam dosya okunur. Makbuz imzalı kanıt, yeni yetki, atomik çok-dosya snapshot'ı veya yedek değildir. Task mutasyonları/importWorkspace için bu dosya makbuzu vaat edilmez. GÖREV İSTEMCİLERİ İÇİN MAKİNE SÖZLEŞMESİ /ggmes-1d-openapi-v3.json önceki okuma ve dosya yazma kapsamına altı görev mutasyonu ekler: taskCreate, taskClaim, taskRenew, taskUpdate, taskRelease, taskComplete. importWorkspace kapsam dışıdır. /ggmes-1d-tasks-v1.txt davranışı açıklar. Her mutasyon yazma rolü ve idempotencyKey gerektirir. Oluşturma dışında expectedRevision güncel pozitif görev sürümüdür; dosya sürümüyle karıştırılmaz. Claim/renew leaseSeconds 60–3600 saniye. Update/release/complete için işlem anında geçerli sahiplik gerekir. Complete güncel bir dosya path/revision kanıtı ister; sunucu SHA-256 hesaplar. Bu, içeriğin doğru olduğuna dair değerlendirme değildir. Görev durumunu taskRead ile geri okuyun; dosya cursor'u görev ilerlemesini kapsamaz. Şemadaki UTF-8 bayt uzantılarını her doğrulayıcı uygulamaz; sunucu kesin sınırdır. Şema erişim, otomatik görev alma veya yeni kimlik sağlamaz. İÇE AKTARIM MAKİNE SÖZLEŞMESİ /ggmes-1d-openapi-v4.json önceki kapsamı korur ve importWorkspace ekler. args tek öğelidir: {format:"ggmes-1d",version:1,files:[{path,content}]} nesnesi veya bu nesnenin JSON metni. Dış HTTP gövdesi her iki biçimde de JSON'dur. İçe aktarma yalnız yeni yollar ekler; mevcut dosyayı güncellemez/üzerine yazmaz. Paket içinde yinelenen veya alanda mevcut yol varsa işlem tümüyle reddedilir. Dosya başına256KiB, alan32dosya/toplam2MiB, dışHTTPisteği1MiB sınırı uygulanır. JSON metninin dış gövdede kaçışları da 1MiB hesabına dahildir. Boş files dizisi kabul edilir; dosya eklenmez. Yetki/idempotency yine zorunludur. Sonuç imported,paths,cursor içerir; dosya yazma makbuzu vaat edilmez. Bu paket görevleri veya geçmişi taşımaz; tam yedek/kurtarma olarak kullanmayın. Metin içindeki JSON'u her genel şema doğrulayıcısı çözümlemez; sunucu sınırları ve çalışma alanı çakışma kontrolleri her zaman geçerlidir. HTTP ORTAK ALAN ÖZETİ — OpenAPI /ggmes-1d-openapi-v5.json GET /v1/resume, AYNI ortak sunucu endpointinde Authorization: Bearer ile. Okuma rolü yeterlidir; sorgu parametresi kabul edilmez. Anahtar URL'ye konmaz. Yanıt {ok:true,result}; bu zarfın TAMAMI en çok2048 UTF-8 bayttır. Tek kalıcı snapshot içinden dosya path/revision ve görev id/revision/status döner. İçerik, görev başlığı, not veya kimlik anahtarı içermez; no-store uygulanır. result.cursor kalıcı dosya olay cursor'udur; cursorKnown:true, cursorScope:file-events-only. Görev sürümleri ayrıdır. pendingServerCount ve pendingUiCount null: bilinmiyor. Kırpma omittedFiles/omittedTasks/truncated ile belirtilir; yok sayılmamalıdır. authority:false ve backup:false. Özet yetki, yedek veya otomatik devam mekanizması değildir. Keşif /v1/capabilities içindeki httpEndpoints alanındadır; RPC yöntemi eklenmedi. Tarayıcıdaki yerel resume özeti ayrı yetenektir; onun cursor/pending sınırları değişmedi. TARAYICI ORTAK ÖZET KÖPRÜSÜ — remote-v5 Mevcut yetkili bağlantı kurulduktan sonra await GGMESConnection.resume(). API panelindeki Ortak devam özetini oku düğmesi aynı tek GET /v1/resume isteğini yapar. Anahtar yalnız Authorization başlığındadır; URL veya özette yoktur. Bağlantısız çağrı SHARED_REQUIRED ile kapanır; yerel özete sessiz dönüş yoktur. Tam yanıt zarfı 2048 UTF-8 bayt, workspace ve metadata şeması doğrulanır. Bu çağrı gözlenen polling cursor'unu ilerletmez; otomatik tekrar veya paylaşım yapmaz. Mevcut GGMESResume.capture() ayrı kalır: consistency=non-atomic; iki yöntemin cursor ve pending alanları birbirinin yerine kullanılamaz. Ortak özette iki pending sayacı null kalır; bilinmeyen sunucu işi sayısı sıfır diye sunulmaz.