Müşteri iadeleri

Uyumluluk: Pactmark 0.2.x. Bu senaryo çalışma-zamanı etki ve karar yüzeylerini kullanır. Genel yazım cephesi şu anda okuma araçlarını sunar — bkz. Sınırlar ve bu sınırı başarıyı taklit etmek yerine dürüstçe gösteren approval-purchase-boundary örneği.

Durum

Bir destek temsilcisi bir iade talebini ele alıyor. Asistan siparişi toplamalı, politikaya göre uygunluğu denetlemeli, tutarı hesaplamalı ve — bir insan onaylarsa — ödeme sağlayıcısı üzerinden iadeyi gerçekleştirmeli. Ajan mühendisliğindeki her zor problem bu tek akışta ortaya çıkar:

Etki geri alınamaz

Para çıkar. Geri alma yoktur; yalnızca kendisi de bir iş eylemi olan telafi edici bir işlem vardır.

Tutar model etkisiyle oluşur

Onu bir model hesapladı. Bir insan modelin anlatısını değil normalize edilmiş değeri görmeli.

API zaman aşımına uğrayabilir

Kaybolan bir yanıt, iadenin yapılıp yapılmadığı hakkında hiçbir şey söylemez.

Birileri bunu soracak

Üç ay sonra, bir itirazda, belirli bir işlem kimliğiyle.

WorkOrder

const request = createWorkOrderRequest({
  agent: { id: "support-refund-agent", version: "2.1.0" },
  goal: "ORD-88213 siparişi için iadeyi değerlendir ve onaylanırsa gerçekleştir.",
  input: { orderId: "ORD-88213", reason: "damaged_on_arrival" },
  context: {
    roleFamily: "customer_support",
    workflowId: "refund-v2",
    riskClass: "high",
  },
  workMode: "augment",
  autonomyMode: "delegate_review",
  decisionOwner: { mode: "registered_role", role: "refund_approver" },
  purpose: { code: "customer_service", registryVersion: "support@3" },
  dataClass: "confidential",
  retention: { mode: "host_policy", policyId: "support-7y" },
  requestedCapabilities: ["orders:read", "payments:refund"],
  budget: {
    maxTurns: 8,
    maxModelCalls: 8,
    maxToolCalls: 6,
    maxActiveExecutionMs: 60_000,
    monetaryCeiling: {
      amount: 500,
      currency: "EUR",
      maximumPriceBoundVersion: "eur-2026-q3",
      maximumPriceBoundExpiresAt: "2026-09-30T00:00:00Z",
    },
  },
  deadline: "2026-08-05T18:00:00Z",
});

İşin çoğunu üç detay yapar:

refund_approver

İsteyen kişi otomatik olarak onaylayabilecek kişi değildir. Destek temsilcileri iade açar, onaylayanlar onaylar.

delegate_review

Koşunun işi yapmasına izin verilir ve çıktı “tamamlandı” sayılmadan önce incelenir.

500 EUR

Açık bir fiyat-sınırı sürümü ve son kullanma tarihi olan katı bir tavan. Üzerinde, kim ne onaylarsa onaylasın koşu ilerleyemez.

Politika

definePolicy({
  id: "support.refund.policy",
  implementationVersion: "2.1.0",
  default: "deny",
  rules: [
    { riskClass: "R1", decision: "allow_with_grant" },   // siparişi oku
    { riskClass: "R2", decision: "allow_with_grant" },   // talebe not düş
    { riskClass: "R4", decision: "require_approval" },   // iadeyi gerçekleştir
  ],
});

R3 ve R5 için kural yok, dolayısıyla reddediliyorlar. Bu bir eksiklik değil — varsayılanın doğru çalışmasıdır.

Araçlar

security: {
  riskClass: "R1",
  dataClasses: ["confidential"],
  reversibility: "not_applicable",
  requiredScopes: ["orders:read"],
  egress: {
    mode: "allowlist",
    destinations: ["https://orders.internal.example.com"],
    methods: ["GET"],
    credentialSlots: ["orders.api"],
  },
  networkEnforcement: "required",
  maxCallsPerRun: 3,
  timeoutMs: 4_000,
}

security: {
  riskClass: "R4",
  dataClasses: ["confidential"],
  reversibility: "irreversible",
  requiredScopes: ["payments:refund"],
  egress: {
    mode: "allowlist",
    destinations: ["https://api.payments.example.com"],
    methods: ["POST"],
    credentialSlots: ["payments.api"],
  },
  networkEnforcement: "required",
  maxCallsPerRun: 1,
  timeoutMs: 15_000,
  costCeiling: 500,
}
// etki stratejisi: reconcilable
// sağlayıcı idempotency anahtarıyla sorgulamayı destekliyor

İade aracında maxCallsPerRun: 1. Model bir şekilde aynı koşuda ikinci bir iade önerirse, politika düşünmek zorunda kalmadan tavan reddeder.

Onay

Şekil 1. Onaylayan normalize edilmiş bir önizleme görür, kimliğini yeniden doğrular ve tek kullanımlık bir kanıtı tüketir. Kanıt asla tarayıcıdan, bir log satırından veya modelden geçmez. Onaylayanın gerçekte gördüğü:

Alan	Değer
`operationClass`	`payment.refund`
`normalizedTarget`	`payments:acct_9f21/order_ORD-88213`
`materialConsequence`	”64,90 € müşterinin 4417 ile biten kartına iade edilecek.”
`reversibility`	`irreversible`
`contentDigest`	`sha256:…` — gönderilecek tam yük
Risk sınıfı	R4
Politika	`support.refund.policy` özeti
Grant	`grant_01J…`, 14 dakika sonra dolar

Tutarın materialConsequence içinde, modelin yazdığı bir cümleden değil normalize edilmiş yükten türetilerek göründüğüne dikkat edin. Modelin anlatısıyla yük çelişirse insan yükü görür.

Ödeme API’sinin zaman aşımına uğradığı gün

Şekil 2. reconcilable, bunların hiçbiri olmadan önce araca kaydedilmişti. Kurtarma yolunu doğaçlama değil meşru kılan da bu önceden yapılmış beyandır. Sıra:

EffectPrepared

Siparişten ve idempotency anahtarından türetilmiş bir effectKey ve strategy: "reconcilable" ile.

EffectDispatched

deneme. POST gider.

Bağlantı düşer

Yanıt yok. EffectUncertain, ardından effectMayHaveOccurred: true ile EffectNeedsReconciliation.

Koşu park eder

Yeniden denemez. “İade başarısız” diye de başarısız olmaz, çünkü bu yanlış bir ifade olurdu.

Mutabakat sorgular

npx pactmark effects reconcile <runId> <effectId> \
  --resolution '{"kind":"recovered_acknowledgement","providerRef":"re_1Nc…"}'

Sağlayıcı idempotency anahtarıyla sorgulanır. İade varsa gerçek sonucu kaydedilir.

Ya da dürüstçe terk edilir

Sağlayıcı yanıtlayamıyorsa abandon_uncertain, etkinin gerçekleşmiş olabileceğini kaydeder. Ona bağımlı her şey KAF_EFFECT_ABANDONED_UNCERTAIN üretir. Bu sürtünme amacın kendisidir.

Yaygın alternatifle karşılaştırın: zaman aşımında yeniden dene. Kusursuz idempotency’si olmayan bir ödeme sağlayıcısında bu, çifte iadedir. Pactmark, kesinti öncesinde bu iki hata biçiminden hangisini kabul etmeye razı olduğunuza karar vermenizi ister.

Kanıt

{
  "claim": {
    "statement": "64,90 €'luk bir iade, refund_approver rolündeki bir onaylayan tarafından yetkilendirildi ve ödeme sağlayıcısı tarafından onaylandı.",
    "claimType": "authorised_financial_effect",
    "scope": "yalnızca run_01J8…"
  },
  "supports": [
    "Onaylayan kimliğini yeniden doğruladı ve tam bu etki önizlemesine bağlı tek kullanımlık bir challenge tüketti",
    "Gönderilen yük özeti, önizlemede gösterilen özetle eşleşiyor",
    "Sağlayıcı effect_01J8… altında kaydedilmiş bir onay döndürdü"
  ],
  "doesNotProve": [
    "İadenin ticari olarak doğru veya politikaya uygun olduğunu",
    "Müşterinin parayı aldığını",
    "Sipariş servisinden okunan verinin doğru olduğunu"
  ],
  "workSplit": {
    "ai": { "kind": "numeric", "value": 4, "unit": "tool_calls" },
    "human": { "kind": "numeric", "value": 1, "unit": "decisions" },
    "description": "Asistan hazırlayıp önerdi; bir insan onaylayan etkiyi yetkilendirdi."
  }
}

doesNotProve listesini yeniden okuyun. “Müşterinin parayı aldığını” ile “sağlayıcı iadeyi onayladı” gerçekten farklı iddialardır ve bunları karıştırmak itirazların kötü gitme biçimidir.

Hâlâ sizde olanlar

Masa limiti

500 € sizin seçtiğiniz bir sayı. Pactmark doğru olsun olmasın onu sadakatle zorlar.

Onaylayanın anlayışı

Doğru bir önizleme yine yanlış okunabilir. TM-05 bu artık riski açıkça kaydeder.

Sağlayıcı idempotency'si

reconcilable, sağlayıcı hakkında sizin iddianızdır. Yanlışsa strateji de yanlıştır.

Park edilmiş etkileri çözecek biri

Park edilmiş koşular, kimsenin açmadığı bir panele değil nöbetteki bir insana ihtiyaç duyar.

Onay entegrasyonu

Operatör akışını doğru kurmak.

Araçlar ve etkiler

Stratejinin neden önceden kaydedilmesi gerektiği.

​Durum

Etki geri alınamaz

Tutar model etkisiyle oluşur

API zaman aşımına uğrayabilir

Birileri bunu soracak

​WorkOrder

​Politika

​Araçlar

​Onay

​Ödeme API’sinin zaman aşımına uğradığı gün

​Kanıt

​Hâlâ sizde olanlar

Masa limiti

Onaylayanın anlayışı

Sağlayıcı idempotency'si

Park edilmiş etkileri çözecek biri

Onay entegrasyonu

Araçlar ve etkiler

Durum

WorkOrder

Politika

Araçlar

Onay

Ödeme API’sinin zaman aşımına uğradığı gün

Kanıt

Hâlâ sizde olanlar