# @doil-operations-contract doil.operationsContract/v1
# @contract-file "cost-capped-5g-remedy.doil"
# @contract-title "Apply the approved RM40 CAC parameter to the Malaysia 5G product configuration"
# @contract-exposure {"classification":"public_blueprint","visibility":"public","containsSensitiveData":false,"intendedRecipients":["darknoc_product_automation_operator","telecom_product_owner"]}
# @contract-execution {"kind":"one_shot","maxCycles":1,"expiresAt":"2026-08-11T23:59:59Z","concurrency":1,"failurePolicy":"restore_captured_version_and_escalate","approvalPolicy":"human_required_before_entrypoint","handler":"apply_approved_cac_remedy","trigger":null}
# @contract-portability ["noc_agent","rpa","runbook","workflow","agentic"]
# @contract-test-clock "2026-08-04T17:30:00.000Z"
# @contract-requirement[OBJ-001] {"category":"objective","criticality":"required","derivedFrom":["desk://run/run_cEGd9-Gjk2CvHEUPOmbE2","desk://claim/clm_2c7f2mcvc","desk://scene/scn_2aDVI_EzIZcAfxQNXJHHw"]}
# @intent[OBJ-001] Apply the approved RM40-per-relationship acquisition-cost parameter to the governed DarkNOC product configuration resource pl_postpaid_5g, preserve every non-target field, verify the effective value and exact allowed diff, and restore the captured prior version if any postcondition fails.
class ApplyApprovedMalaysia5GCacRemedy < BaseAgent
  intent "Apply the approved RM40-per-relationship acquisition-cost parameter to the governed DarkNOC product configuration resource pl_postpaid_5g, preserve every non-target field, verify the effective value and exact allowed diff, and restore the captured prior version if any postcondition fails."

  context do
    require geography: "Malaysia"
    require technology: "Consumer 5G product configuration"
    require link: "DarkNOC governed product-configuration API binding"
    require system: "DarkNOC product configuration service"
    require event: "Approved cost-capped 5G remedy handoff"
    require nodes: ["product_configuration:pl_postpaid_5g"]
    require time: { starts_at: "2026-08-04T17:30:00Z", ends_at: "2026-08-11T23:59:59Z" }
    require resource: { type: "product_configuration", id: "pl_postpaid_5g", parameter_path: "economics.cac", unit: "MYR_per_active_relationship" }
    require selected_remedy: { parameter_path: "economics.cac", set_to: 40, unit: "MYR_per_active_relationship" }
    require allowed_diff: ["economics.cac"]
    require protected_fields: ["identity", "market", "tam", "launch_schedule", "adoption_model", "lever_instances", "campaigns", "build_cost", "pricing", "customer_assignments", "network_configuration"]
    require execution_window: { starts_at: "2026-08-04T17:30:00Z", ends_at: "2026-08-11T23:59:59Z", max_attempts: 1 }
    require run: "desk://run/run_cEGd9-Gjk2CvHEUPOmbE2"
    require approved_claim: "desk://claim/clm_2c7f2mcvc"
    require approved_scene: "desk://scene/scn_2aDVI_EzIZcAfxQNXJHHw"
    require evidence_boundary: "RM40 is the approved modeled CAC parameter. The receiver must bind and validate the live resource; this contract does not treat modeled spend or relationships as live telemetry."
    require user: :approved_darknoc_product_operator
  end

  tools do
    read_current_product_configuration description: "Resolve exactly one governed product configuration resource, capture its current version and complete configuration, and refuse ambiguous or missing bindings", effect: "read", vendor_op: "receiver_owned", parameters: ["resource"]
    validate_operational_preconditions description: "Confirm approval, execution window, compare-and-set version, parameter unit, target-field writability, and absence of another in-flight mutation", effect: "read", vendor_op: "receiver_owned", parameters: ["current_configuration", "selected_remedy", "execution_window"]
    apply_approved_parameter_patch description: "Using compare-and-set against the opaque captured snapshot, change only economics.cac to RM40 per active relationship on pl_postpaid_5g and return a change receipt", effect: "external_change", vendor_op: "receiver_owned", parameters: ["resource", "captured_snapshot", "selected_remedy", "allowed_diff"]
    verify_effective_product_configuration description: "Read back the changed resource and prove economics.cac equals RM40 with the required unit while every protected field remains byte-equivalent to the opaque captured snapshot", effect: "read", vendor_op: "receiver_owned", parameters: ["resource", "change_receipt", "captured_snapshot", "selected_remedy", "allowed_diff", "protected_fields"]
    restore_captured_product_configuration description: "If verification fails, restore the exact opaque captured snapshot with compare-and-set and return a rollback receipt", effect: "external_change", vendor_op: "receiver_owned", parameters: ["resource", "failed_change_receipt", "captured_snapshot"]
  end

  guardrails do
    pre_execution do
      require :approval
    end
  end

  output do
    stage :operations do
      generate :product_configuration_change_receipt
      present :resource_version_allowed_diff_verification_and_rollback_status
      require :approval
    end
  end

  def apply_approved_cac_remedy
    current = tools.read_current_product_configuration.apply(:resource)
    if current.ready
      preconditions = tools.validate_operational_preconditions.apply(current, :selected_remedy, :execution_window)
      if preconditions.ready
        changed = tools.apply_approved_parameter_patch.apply(:resource, current, :selected_remedy, :allowed_diff)
        verified = tools.verify_effective_product_configuration.apply(:resource, changed, current, :selected_remedy, :allowed_diff, :protected_fields)
        if verified.failed
          tools.restore_captured_product_configuration.apply(:resource, changed, current)
        end
      end
    end
  end
end